Create a workspace

A workspace is backed by one machine that runs its agents. Creating one takes a few minutes in the app: you name it, pick where it runs, and give it an AI provider key. Bopsy sets the machine up for you.

Step 1 — Name your workspace

Open Create workspace in the app and give it a name. You can invite members once it exists.

Step 2 — Choose where it runs

One machine runs the workspace's agents. Pick one of:

• Fly.io Sprite. A hosted machine that sleeps when idle, so you pay only while it is awake. You need an existing Sprite and a Sprites API token from sprites.dev; Bopsy reaches it through the Sprites API, with no SSH.
• DigitalOcean. A new Harness Runtime session, created with your DigitalOcean API token. It pauses when idle.
• My own server. Any Linux machine you can SSH into. See Using your own server below before you continue.

Tokens you enter here are stored encrypted and used only to reach that machine.

Step 3 — Add your AI provider

Choose the provider the agents will use and paste its key:

• Anthropic or OpenAI, with a model name (defaults are suggested), or
• Manifest, or any other OpenAI-compatible router, with its endpoint URL.

The key is written to the workspace's machine. The Bopsy control plane does not keep a copy.

Step 4 — Create

Click Create workspace. Bopsy installs the agent runtime on the machine and shows the progress as it goes. When it finishes you land in the workspace, ready to install agents, invite members and connect knowledge.

Using your own server

If you chose My own server, the machine needs a dedicated Linux user for Bopsy to work as. Do this once per server.

Why a dedicated user

Bopsy installs into that user's home directory and runs as a user-level service. It never needs root. A dedicated user also means you can revoke access later by deleting one account. Don't add the user to the sudo group.

Why linger matters

By default, systemd stops a user's processes when that user logs out. If the install succeeds and then the agent goes offline every time your SSH session ends, this is why.

loginctl enable-linger <user> tells systemd to keep that user's services running when nobody is logged in.

Create the user

SSH into the server as root (or a user with sudo) and run:

sudo adduser <username>

Set a password when prompted.

Enable linger

sudo loginctl enable-linger <username>
loginctl show-user <username> | grep Linger
# Expected: Linger=yes

Choose how Bopsy signs in

In the Create workspace form you can either:

• enter the user's password, which Bopsy uses once to install its own SSH key, or
• generate a key in the form and add the public key to ~/.ssh/authorized_keys for that user yourself. Nothing else is needed; the form can test the key before you continue.

Then enter the host or IP, the SSH port and the username, and create the workspace.

Troubleshooting

The workspace goes offline whenever I close my terminal. Linger isn't enabled. Run sudo loginctl enable-linger <user> and restart the workspace.

"Connection refused" on SSH. The server's firewall is blocking the SSH port. Open it in your provider's console and in ufw or iptables if you run one.

"Permission denied" during install. Check that the user owns its home directory and that ~/.local/bin is writable. The install does not need sudo.