Skip to content
moatboxdocs
Log in
All pages

Quickstart

Sign in to moatbox, create a space, start an agent run and connect to the space from your terminal.

This page takes you from no account to an agent running in a moatbox space, with an SSH connection from your own terminal. moatbox is a hosted service at https://app.moatbox.dev; a space is a virtual machine where agents run. Background on both is in the overview.

1. Sign in

Open https://app.moatbox.dev. Pick Continue with Google, Continue with GitHub, or type your address and press Email me a magic link. The emailed link works once and expires after 15 minutes.

While moatbox is invite-only, an address without an invite goes on the waitlist and gets an email once a place opens.

2. Create a space

Only team owners and admins can create spaces, and the team needs an active plan.

  1. Go to Spaces and press Create space. The space picker's + New space entry opens the same form.
  2. Fill in the form:
    • Team: the team that owns the space. The list holds the teams where you are an owner or admin.
    • Space name: 3 to 32 characters of a-z, 0-9 and -, starting and ending with a letter or digit. The name appears in the space's URL and SSH alias.
    • From: A fresh box, A saved snapshot, or A share code from another team. See Snapshots for the last two.
    • Size: CPU and memory. Every size has a 50 GB disk. See Spaces.
    • Environment: shown when the team has more than one environment. Leave it on the default, or see Environments.
    • Auto-stop: how long the space may sit idle before it sleeps. The default is 10 minutes.
  3. Press Create space.

The dashboard opens the space at https://app.moatbox.dev/s/<space>. Its state reads Starting until the machine is up, then Awake.

3. Start an agent run

  1. On the space's Agents page, press New agent.
  2. Pick the agent: Claude Code, Codex or opencode.
  3. Type the task in the box ("What should the agent do?"). You can also pick a working directory under /workspace, type a branch, or turn on Screen to watch the agent's browser.
  4. Press Start.

The run page opens at https://app.moatbox.dev/s/<space>/runs/<run>. If the agent has no credentials in this space yet, follow Agent sign-in first. Held actions show up on the space's Approvals page; see Approvals.

4. Connect from your terminal

You need macOS (Apple silicon or Intel) or Linux (x86-64 or arm64) for the CLI.

  1. On the space's Overview page, open Open in… and pick Terminal.

  2. Copy the command under Set up this computer once and paste it into your terminal. It looks like this:

    curl -fsSL https://app.moatbox.dev/api/v1/cli.sh | sh -s -- mbx_cli_… my-space

    The command installs the moatbox CLI in ~/.local/bin, creates ~/.ssh/moatbox_ed25519 if it is missing, signs this computer in, adds the key to your account and writes a Host moatbox-my-space block into ~/.ssh/config. The code inside works once and expires after 15 minutes; press New command for a fresh one.

  3. Connect:

    ssh moatbox-my-space

If ~/.local/bin is not on your PATH, the script prints the line to add. The same alias works for scp, sftp and rsync. Connect to a space covers the SSH gateway, other editors, every CLI command and Tailscale.

Next steps

  • Spaces: sleep, auto-stop, resizing, the trash and forks.
  • Environments: give every new space its repositories, variables and setup script.
  • API keys: script moatbox from CI or your own tools.