Connect your agent · Docs

Your agent reaches wack through a connect URL, an MCP server address. There are two kinds:

Your account's URL looks like https://api.wack.sh/mcp/wac_…. It gives an agent all your boxes, and lets it make new ones and delete the ones it no longer needs. This is the one to use.
A box's URL looks like https://api.wack.sh/mcp/wbx_…. It gives an agent just that box, for when it should see nothing else.

The URL is the credential. Anyone who has it can run commands in the boxes it reaches, so treat it like a password. Both kinds stay hidden until you click Show. Rotate URL gives out a new one, and the old one stops working at once; update every agent that used it. Rotating your account's URL leaves box URLs alone, and the other way round.

The guided setup

Click + next to Connect an agent in the sidebar, or Connect agent under Get set up on Boxes. Pick your agent, then copy the one command, config or link it shows. The page waits for your agent and says Connected as soon as it makes contact.

Your account's URL is also under Settings › Connection, with Show, copy and Rotate URL, and every client's setup under Manual setup.

To connect an agent to just one box, open the box: its Overview walks you through it while no agent is connected, and Connect an agent in the box's ⋯ menu starts it again. The box's URL is in its Settings tab, under Connection.

The one-line setup

The quickest way to set it up by hand is to let your agent do it. Copy the setup line (from the guided setup, under Other ways to connect) and paste it into your agent:

Read https://wack.sh/SKILL.md and connect me to my wack boxes: https://api.wack.sh/mcp/wac_…

The agent reads SKILL.md, adds the server to its own settings without overwriting your other servers, tells you if it needs a restart, and then runs a check in a box. The guided setup shows the connection as soon as the agent makes contact.

To set it up yourself, follow the steps for your client below (the same ones are under Manual setup in Settings). Replace <url> with your connect URL.

Claude Code

claude mcp add --transport http --scope user wack <url>

--scope user makes wack available in every project. Start a new session, or run /mcp in a running one, to see the wack tools.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.wack]
url = "<url>"
tool_timeout_sec = 900

tool_timeout_sec lets long commands finish: box_exec can run for up to 900 seconds, which is longer than Codex waits by default. Restart Codex after saving.

Cursor

Pick Cursor in the guided setup for an Add to Cursor button that installs the server in one click. To do it by hand, add this to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "wack": {
      "url": "<url>"
    }
  }
}

Claude (desktop, web and mobile)

Claude adds remote servers as custom connectors, and they follow your Claude account:

In Claude, open Customize › Connectors.
Click Add custom connector, name it wack and paste the URL.
If Claude asks how people sign in, choose No sign-in. Then click Add.

On Team and Enterprise plans an owner adds it under Organization settings › Connectors (Add › Custom › Web); members then click Connect.

VS Code

code --add-mcp '{"name":"wack","type":"http","url":"<url>"}'

Or add it to .vscode/mcp.json in a workspace:

{
  "servers": {
    "wack": {
      "type": "http",
      "url": "<url>"
    }
  }
}

Other clients

wack speaks MCP over streamable HTTP, so any client that supports remote servers can connect. Clients name the fields differently:

Most clients take "type": "http" (some say "streamable-http") and a "url".
Gemini CLI uses "httpUrl". Also set "timeout": 900000 so long commands can finish.
Windsurf and Devin use "serverUrl".
VS Code puts servers under "servers", not "mcpServers".

For a client that only supports local (stdio) servers, bridge it with mcp-remote:

npx -y mcp-remote <url>

Agent skill

The wack skill tells Claude Code and Codex when a job belongs in a box: heavy builds and dev servers, parallel jobs, headed browsers and visual tests, or a clean Linux machine. It is optional and holds no secret; the connect URL above is still what gives your agent the boxes. Install it with:

curl -fsSL https://wack.sh/install | sh

It saves the skill to ~/.claude/skills/wack/SKILL.md, and to ~/.codex/skills/wack/SKILL.md if you use Codex. Add -s -- --project after sh to install it into the current project's .claude/skills instead. Run it again to update, then restart your agent. You can read the skill at /skill/SKILL.md.

The tools

Tool	What it does	Box URL
`box_docs`	Returns the box manual. Agents call it once before their first job.	Yes
`box_list`	Lists your boxes and their state. On a box URL it marks the one the URL belongs to.	Yes
`box_create`	Makes a new box and returns once it is awake. Optional `name`, `size`, `screen`, `image` (start as a copy of a saved image), `setup` (a recipe applied before it returns), and `ephemeral` for a box that deletes itself when it goes to sleep.	No
`box_delete`	Deletes a box and everything on its disk. It can't be undone.	No
`box_start`	Wakes the box. Safe to call when it is already awake.	Yes
`box_stop`	Puts the box to sleep. Refuses while something is running.	Yes
`box_exec`	Runs a bash command as root. Default timeout 300 s, up to 900 s.	Yes
`box_upload`	Writes a file into the box from text or base64 content.	Yes
`box_download`	Reads a file from the box. Images come back as images.	Yes
`box_screenshot`	Screenshots a URL or an HTML file in the box and returns the image.	Yes
`box_setup`	Applies a setup recipe to the box: apt packages, a Chrome version, private repos, fonts, environment variables and commands.	Yes
`box_screen`	Turns on the box's screen (a virtual display) if needed, clicks, types or scrolls on it, and returns a picture of it.	Yes
`box_image_save`	Saves a box as an image, so new boxes can start as a copy of it.	No
`box_image_delete`	Deletes a saved image. Boxes started from it keep everything.	No

On your account's URL, every tool that works on a box takes box: the box's id (box_…) or its exact name, as box_list shows them. On a box's URL, every tool works on that box. Tools that need a box running wake it first, which takes about a second.

Boxes your agent makes

Boxes your agent makes with box_create are ordinary boxes: they show up on Boxes, count toward your plan and have their own Overview, Files, Screen, Activity and Settings. Agents make extra boxes to run work side by side, such as testing several repos at once or trying ideas that must not touch each other.

box_create takes the same choices as the New box dialog, and a few more:

size: standard, large, xl or gpu (Sizes and GPU boxes).
screen: turns the box's screen on right away.
setup: a recipe applied before the box is handed over, and image: a saved image to start from (Setups and images).
ephemeral: a throwaway box, described below.

A box made with ephemeral: true is a throwaway. It says Temporary on its card and deletes itself, with everything on its disk, the first time it goes to sleep. Your agent copies out what it needs before then.

Your plan caps how many boxes you have and how many are awake at once (Limits). At the cap, box_create fails with a message that says so, and your agent can put a box it made to sleep, delete one it made or ask you to upgrade. wack never stops or deletes a box to make room.

Troubleshooting

"This connect URL is no longer valid." The URL was rotated. Copy the current one from Settings › Connection (or the box's Settings, for a box's URL) and update the client.
A tool asks for box. It's on your account's URL, which reaches every box. Your agent calls box_list and passes the box's id or name.
Long commands time out in Codex or Gemini CLI. Raise the client's tool timeout as shown above.
The tools don't show up. Most clients load MCP servers at startup. Restart the client or start a new session.
A tool result says your awake hours are used up or your trial has ended. The message explains what happened and links to billing, so your agent can pass it on to you.
box_create says a limit is reached. Your plan caps boxes, boxes awake at once and GPU boxes (Limits). Your agent can put a box it made to sleep or delete one, or you can upgrade.
Calls answer "Too many requests". Your account's URL allows 3,000 MCP requests a minute and a box's URL 300. The agent waits and tries again.

Last updated September 30, 2026