Skip to main content
amika rig open opens a remote rig in Cursor, VS Code, Claude Desktop, Codex, Paseo, or Herdr over SSH. Cursor is the default. amika rig code and --editor still work as aliases for amika rig open and --app.
rig open, --app, and the herdr app ship in the next CLI release. In v0.23.0 and earlier, run amika rig code <name> --editor <app> instead. It supports every app except herdr.

​
Prerequisites

  • An SSH identity. Create one with amika secret ssh-keygen.
  • For Cursor or VS Code, its CLI (cursor or code) on your PATH and the Remote - SSH extension installed.
  • For Herdr, the herdr CLI on your PATH.

​
Open the rig

Use cursor or vscode to open the repository in that editor. Use claude to register the rig as a Claude Desktop SSH environment, then select Amika: <rig-name> from its environment dropdown. Use codex to add the rig as a Codex remote connection, then enable the host in Settings > Connections. See Codex app. Use paseo to print the SSH host to add in Paseo. See Paseo. For Cursor and VS Code, the command opens the repository directory. If the file explorer is not visible, press Cmd+Shift+E. To open a different directory, pass --path with an absolute path or a path relative to the rig workspace:
--path has no effect with paseo or herdr.

​
Add the rig to Herdr

--app herdr runs herdr machine add with the rig’s SSH host and labels the machine with the rig name. Herdr connects to the rig over SSH to prepare its remote server, and may prompt during setup.
If Herdr already has the rig, the command says so and does nothing. If another machine already uses the rig’s name as its label, the command names that machine so you can remove it with herdr machine remove and retry.

​
Use another Remote-SSH editor

Any editor that reads your ~/.ssh/config and supports remote SSH can use the Amika-managed host alias.
  1. Run amika rig open dev-box once to write the rig alias to ~/.ssh/amika.conf and include it from your SSH config.
  2. Open your editor’s remote-SSH host picker and select <rig-name>.<rig-id>.<environment>.amika.
  3. Open the repository directory in the rig, typically under /home/amika/workspace.

​
Use a browser

To work with an agent without a local editor, open the rig in the web UI and choose OpenCode or Pi Web from Open with … while the rig is running. The agent’s web console opens in a new tab through a signed, short-lived URL, so there is no password to set.

​
What it does

Under the hood, amika rig open:
  1. Creates a direct SSH session and pins the rig’s Ed25519 host key.
  2. Builds an alias in the format <rig-name>.<rig-id>.<environment>.amika.
  3. Ensures ~/.ssh/config includes the Amika-managed ~/.ssh/amika.conf.
  4. Adds a concrete host entry so editors can discover the rig. An environment-scoped wildcard entry supplies the shared connection settings:
  1. Opens or configures the selected editor or coding agent with the alias.
The concrete entry intentionally has no connection options. OpenSSH gets those from the wildcard entry for the current Amika environment. This lets one config support rigs from multiple control planes without sending an alias through the wrong proxy.

​
Troubleshooting

  • cursor or code CLI is not installed or not in PATH: install the editor’s shell command from its command palette.
  • unsupported app: pass one of cursor, vscode, claude, codex, paseo, or herdr.
  • Cursor or VS Code opens but cannot connect: make sure its Remote - SSH extension is installed.

​
Next steps

SSH and connect

Rig lifecycle