Skip to content

Start workspaces from Agents

Some servers stop: a cloud machine you turn off to save money, a Codespace that idles out, a Docker container you stopped. Usually a stopped server is just offline, and you have to start it yourself in the provider's console or in Terminal.

Give the control plane a workspace provider and link the server to its workspace. A stopped server then shows Start on every screen. The control plane starts the machine, waits for its agentsd to connect, and the server comes online by itself.

Before you start

  • A control plane on one machine. The one on your Mac works. Several copies sharing a bucket can't run providers yet.
  • A server already added, or a workspace you can reach over ssh. See Add a server.
  • The provider's command-line tool on the Mac that runs the control plane, signed in: docker, doctl, gh, coder or gcloud. The provider runs there, not on the server. That is how it can start a server that is down.

Add a provider

  1. Open Settings ▸ Control plane ▸ Providers on the Mac and choose Add Provider….
  2. Pick the kind:
  3. Docker: containers on the Mac that runs the control plane.
  4. DigitalOcean: droplets with a tag. Agents reaches each one as root@ its address unless you say another user.
  5. Codespaces, Coder, or Workstations (Google Cloud Workstations).
  6. Your commands: one workspace, given as the commands you already use to start and stop it, such as cws start devstack-1. A status command is optional; it prints running or stopped.
  7. MCP server: a provider of its own, or another MCP server with a tool map. See Add a workspace provider.
  8. Fill in its few fields. If it needs a token, add it under Secrets. A secret stays on the control plane and is never shown again.
  9. Choose Add. Agents checks the provider and lists its workspaces. If it can't, the sheet says why, in the provider's words.
  • For a server you already have: in Settings ▸ Control plane ▸ Hosts, open its ··· menu, choose Link to Workspace…, pick the workspace and choose Link.
  • For a workspace that isn't a server yet: start it, then choose Add as Host… beside it on the Providers page. Add a Server opens over ssh, with the provider's address filled in. The new server is linked to the workspace once it joins.

A workspace belongs to one server at a time: linking it to another moves the link.

Start a stopped server

When a linked server's workspace is stopped, its row says Stopped and the strip over its chats says devbox is stopped, with Start. Press it on the Mac, the iPhone, the iPad or the browser.

The strip then says:

  1. Starting devbox… while the provider starts the machine.
  2. Waiting for devbox to connect… once it is up. If the server reaches the control plane through an ssh tunnel, the tunnel opens straight away.
  3. devbox started but agentsd didn't connect; starting it over ssh… if agentsd hasn't connected after two minutes. Agents starts it over ssh, as an install leaves it, and installs nothing.

The strip goes away when the server is online. A timer beside the words shows how long the start has taken so far. Pressing Start again on any screen while it starts does nothing more.

If the start fails, or the server hasn't connected after ten minutes, the strip and the row say why and offer Start again.

Stop a server

Choose Stop on its row in Settings ▸ Control plane ▸ Hosts. If agents are working there, Agents names them and asks first. The row says Stopping… and then Stopped.

Start when used and stop when idle

A linked server's ··· menu has two settings:

  • Start when used, on by default.
  • Stop when idle, after 30 minutes by default.

Both are kept with the link.

Start when used

With Start when used on, you don't have to press Start. Send a prompt to an agent on the stopped server, or start a new agent in one of its projects, on the Mac, the iPhone or the web page:

  • The control plane keeps what you sent and starts the workspace.
  • The chat shows your prompt as a dashed bubble, with Waiting for devbox to start under it. A new agent's chat opens at once with its first prompt waiting the same way.
  • When the server connects, the prompt goes, once, in the order it was sent. A new agent is made then, and its chat opens.

What was sent is kept by the control plane, not by the app. You can close the app or lock the phone, and it still goes. Up to 20 can wait for one server.

  • To take one back, press × beside it. The workspace keeps starting.
  • If the start fails, each waiting prompt says Not sent and why, with Try Again.
  • Attachments can't wait. Send the words alone, or start the server first.

Only prompts and new agents start a workspace. Reading a chat or a file on a stopped server doesn't. With Start when used off, a prompt to a stopped server is refused, and its strip offers Start.

Stop when idle

A workspace costs money while it runs. With Stop when idle on, Agents stops it once its server has been idle for the whole time you chose: 15, 30 or 60 minutes, or 2 hours. Idle means:

  • no turn running,
  • no agent waiting on your answer,
  • and no terminal or project shell open.

A turn starting in that time starts the count again. When Agents stops it, its row and the strip over its chats say devbox was stopped by Agents after 30 minutes idle. With Start when used on as well, your next prompt starts it again.

A server's scheduled workflows don't run while it is stopped. Its row warns you when it has some and Stop when idle is on.

A server on a build of Agents from before this never says whether it is idle, so it is never stopped as idle. Update it from its row.

Make a new workspace

For a provider that can make workspaces, its card in Settings ▸ Control plane ▸ Providers has New Workspace….

  1. Give it a name, and make its choices: its size or region, say.
  2. Choose Make…. Agents says what it will make and, if the provider says, what it costs.
  3. Choose Make.

The new workspace shows Joining… until it has installed Agents and joined. Then it is linked to its host. A provider that can't install on first boot opens Add a Server with the new workspace filled in, as Add as Host… does.

To delete one, choose Delete Workspace… in its server's ··· menu on the Hosts page. Agents names what is lost first: the workspace, everything on its disk, and the server with its agents.

If it doesn't work

  • The provider can't list. Its card says why, and shows what it last listed. Check its command-line tool is installed and signed in on the Mac that runs the control plane, then choose List Again in its ··· menu.
  • "workspace-commands isn't installed beside the control plane". This build of Agents Host doesn't carry the command provider yet. Set AGENTS_WORKSPACE_COMMANDS to a build of it for the control plane, or wait for a build that has it.
  • The server starts but never connects. Make agentsd start when the machine boots: on Linux, loginctl enable-linger $USER keeps the user's services running with nobody logged in. Or give the workspace an ssh address, so Agents can start agentsd itself.