Skip to main content

Quickstart

From a Mac or a Linux machine with nothing installed to an agent that answers.

1. Install​

curl -fsSL https://usewisp.io/runtime/install.sh | sh

The installer asks:

Start the Runtime in the background now and at every login? [Y/n]

Press Enter. Wisp then runs as a background service (a launchd agent on a Mac, a systemd user service on Linux), so you never have to start it by hand.

Once the service is up, the installer offers to sign you in:

Log in now? [Y/n]

Press Enter and follow step 2 right there; you can then skip it below.

The installer does everything else for you: it downloads and verifies the release, puts the wisp command in ~/.wisp/bin, adds that folder to your PATH, and creates ~/.wisp/runtime.json with a random access token. You do not need to configure anything.

The installer ends with the line that loads the new PATH into your terminal, such as source ~/.zshrc (. ~/.profile for sh and dash). Run it, or open a new terminal, then check:

wisp status
# login_required (wisp 0.1.0, serve)
# account not signed in — wisp login
# ! bash_run is ask, which a Run cannot answer — wisp permissions set bash_run allow --project .

login_required is expected if you did not sign in during the install: the Runtime is up and waiting for you. The bash_run line is a reminder, not an error; see Permissions before you follow it.

If something does not answer, wisp doctor checks the whole setup and prints the command that fixes each problem.

Linux

On Linux the installer needs minisign or OpenSSL 3 to verify the release signature, and stops if neither is installed. It also warns when bubblewrap is missing: the agent's bash_run tool needs it once you turn its sandbox on, and Wisp inside Hermes needs it for its sandbox around Hermes. On Debian or Ubuntu: sudo apt install minisign bubblewrap.

On a server the installer turns lingering on, so the service keeps running after you log out. If it warns that it could not, run the sudo loginctl enable-linger command it prints.

Answered "no", or there was no terminal to ask on?

Then nothing is running yet. Start the Runtime yourself and keep that terminal open:

wisp serve

On Linux, wisp serve first needs a key file for its encryption key; see the encryption key on a server. The service makes one for you, which is one more reason to say yes to it.

Run the remaining commands in a second terminal. To get the background service later, see Install, update, uninstall.

Already use Wisp Desktop on this Mac?

Then the installer does not offer the service, because the app already runs a Runtime on the same data. Keep the app open: wisp commands talk to the Runtime inside it, and you are already signed in. See Install, update, uninstall.

2. Sign in​

The Runtime reaches the model through your Wisp account.

wisp login

This opens a browser and waits up to 5 minutes for you to sign in.

On a server without a browser, or over SSH, it does not wait for one. It prints a URL instead (--manual does the same anywhere): open it on any device, sign in, then copy the address the browser ends up on (something like 127.0.0.1:49873/callback?code=…; the page itself will not load, and that is fine) and paste it back into the terminal.

wisp login --manual

Once signed in, it prints ready and your account. wisp status now says:

wisp status
# ready (wisp 0.1.0, serve)
# account you@example.com

If you skip this step, the first wisp run at a terminal asks whether to sign in first.

3. Add money to the balance​

wisp run may be paid from your account's prepaid balance alone, not from the plan that pays for chats in Wisp Desktop. See what you have:

wisp billing status
# balance $0.00
# auto-reload off

If it shows only these two lines, terminal Runs are paid from the balance, so add some before your first Run. The command prints a payment link, which you can open on any device, and waits until you have paid:

wisp billing topup 10
# https://checkout.…
# paid: $10.00 added to the balance

Plan and balance explains what each one pays for, and how to top up automatically.

4. Ask something​

cd into the folder the agent should work in. That folder becomes the Session's Project: the agent works there, and a file call outside it asks you first.

cd ~/projects/thing
wisp run "read the source and tell me what this project does"

The first line, session 6b4f2a7e-…, goes to stderr; the answer goes to stdout. To keep talking in the same conversation, pass that id:

wisp run 6b4f2a7e-… "now write a README for it"

Some useful commands to go with it:

wisp sessions list # this folder's Sessions
wisp cancel 6b4f2a7e-… # stop a Run that is taking too long
wisp models # models you can pick with: wisp run --model <id>

5. Connect a service​

The agent has file, shell and web tools built in. Anything else comes from a connector, an MCP server you add once and then enable for each Project. For example, GitHub:

wisp connectors add github --http https://api.githubcopilot.com/mcp/ --header-stdin Authorization
# paste: Bearer <your GitHub token>, then press Enter

wisp connectors enable github --project .
wisp permissions allow-connector github --project .

The three commands do three different things:

  1. add stores the connector and its secret. --header-stdin reads the secret from the terminal, so it never ends up in your shell history.
  2. enable makes its tools visible to the agent in this folder.
  3. allow-connector lets those tools run. Nobody is watching a CLI Run to approve a tool call, so a tool with no Rule that allows it is refused. This command allows every GitHub tool in this folder. To allow only some of them, see Permissions.

add does all three in one command when you give it --project and --allow:

wisp connectors add github --http https://api.githubcopilot.com/mcp/ --header-stdin Authorization --project . --allow
wisp connectors list
# github connected

wisp run "list my open pull requests"

Next​