Quickstart

Get a real agent running on Gentity in under a minute. You need one thing: a model provider API key (Anthropic, OpenAI, OpenRouter, DeepSeek, Google, or xAI) that the agent will use to call its LLM.

1. Install the CLI

# macOS / Linux — single-line install
curl -fsSL https://gentity.ai/install.sh | bash

# Or via Homebrew
brew install gentityapp/tap/gentity

Either method drops a single gentity binary into /usr/local/bin. Verify with gentity --version.

2. Mint an API token

Open gentity.ai/dashboard/settings/tokens, click Generate, copy the gn_live_… string (shown once), and hand it to the CLI:

gentity login --token gn_live_...

The token is stored at ~/.config/gentity/config.json with mode 0600. To verify, run gentity compute list — you should see an empty list (or your existing instances) and not a 401.

3. Spin up your first agent

# Claude Code with Anthropic Sonnet 4.5
export ANTHROPIC_API_KEY=sk-ant-...

gentity compute create \
  --agent claude-code \
  --model claude-sonnet-4-5

The CLI prints progress as Fly provisions the microVM:

:: Provisioning isolated microVM…
:: Attaching persistent volume…
✓ Agent cl-x7k2m9 ready in 8.3s
  Open https://cl-x7k2m9.gentity.ai

The URL is your agent's workspace. Open it in a browser to see the agent UI (terminal, file editor, or web UI depending on the agent). Each instance also gets a unique subdomain that's yours alone — treat it like a secret URL, not a public address.

4. Manage running instances

gentity compute list          # what's running
gentity compute open cl-x7k2m9    # open in browser
gentity compute logs cl-x7k2m9 --follow   # tail the container
gentity compute ssh cl-x7k2m9     # interactive shell inside
gentity compute stop cl-x7k2m9    # stop (state preserved)
gentity compute start cl-x7k2m9   # resume
gentity compute delete cl-x7k2m9 --yes    # destroy + volume

You can reference an instance by its full id (cmp8w6wf...), by an unambiguous id prefix (cmp8w6wf, the first 8 chars shown in list), or by subdomain (cl-x7k2m9). The CLI resolves the prefix client-side.

5. Use in CI

Drop your token in GENTITY_TOKEN and the model key in the usual env name; the CLI picks both up automatically.

# GitHub Actions
- name: Install gentity
  run: curl -fsSL https://gentity.ai/install.sh | bash

- name: Spin up a Claude Code reviewer
  env:
    GENTITY_TOKEN: ${{ secrets.GENTITY_TOKEN }}
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    gentity compute create \
      --agent claude-code \
      --model claude-sonnet-4-5 \
      --name "pr-${{ github.event.pull_request.number }}" \
      --detach

Next steps

• Concepts — what an instance, volume, subdomain, and model provider actually are.
• Agent guides— per-agent first-run notes; some agents (Hermes, OpenClaw) need a bit of setup inside the workspace before they're useful.
• CLI reference — every command and flag.