# RightSide: complete agent operating guide

# RightSide

> RightSide is an agent-native deployment finishing layer. Canonical control, runtime, edge, and installer services are live for an invite-only closed beta. Access is allowlisted; public signup is unavailable; beta projects and data are disposable and may be erased before public beta.

## Start
- [Quickstart](https://docs.rightside.host/quickstart): installation, authorization, registration, verification
- [Agent guide](https://docs.rightside.host/agents): completion contract and agent-safe defaults
- [Deploy](https://docs.rightside.host/deploy): application contract and deploy flow

## Reference
- [MCP tools](https://docs.rightside.host/mcp): bounded tools for Claude Code and Codex
- [CLI reference](https://docs.rightside.host/cli): common commands and machine-readable output
- [Troubleshooting](https://docs.rightside.host/troubleshooting): stage-based recovery
- [Security](https://docs.rightside.host/security): credential and authority boundaries
- [Limits](https://docs.rightside.host/limits): current support and non-goals

## Canonical setup
```sh
curl -fsSL https://get.rightside.host/install | sh
rightside doctor --json
```

The one-line installer trusts HTTPS delivery of the bootstrap. The bootstrap verifies the immutable release payload against its manifest-pinned checksum; its own bytes are not out-of-band pinned by the one-line form.

## Recommended Claude Code / Codex prompt
```text
Install and set up RightSide on this machine. Verify that Node.js is 22.13 or newer and that this is Linux x64, WSL2 x64, or Apple silicon macOS. Run `curl -fsSL https://get.rightside.host/install | sh`, let me complete browser authorization, and never ask me to paste a token, device code, cookie, or secret into chat. Then run `rightside doctor --json`. If it passes, inspect this project and deploy it with RightSide. Do not claim success until RightSide returns an HTTPS URL and you verify that URL responds correctly.
```

Do not claim deployment success until the returned HTTPS URL is fetched directly and produces the expected response. Database is disabled by default. Hosted-app authentication is enabled when CLI/MCP creates a project; use explicit public paths or explicit auth:false/--no-auth when required.

## Agent execution loop
1. Run `rightside doctor --json`.
2. Inspect the workload. It must listen on `0.0.0.0:$PORT` and answer its configured health path; the default is `/`.
3. Use `rightside deploy . --name NAME` when completion must include RightSide’s external HTTPS probe. MCP `deploy_project` reports control-plane state and requires a separate direct fetch of the returned URL.
4. On failure, use the structured stage, error code, suggested fix, and redacted logs. Repair only evidence-backed source issues. Avoid blind retries.
5. Read project state with `project_status` or `rightside status NAME --json`, then fetch the exact HTTPS URL directly and require the expected response.
6. Return the exact HTTPS URL and distinguish INSPECTED, IMPLEMENTED, DEPLOYED, or BLOCKED.

## MCP tools
- `login_status`: authorization status and recovery guidance
- `list_projects`: projects visible to the credential
- `create_project`: create a project record
- `deploy_project`: deploy a local directory
- `project_status`: active release, versions, options, and URL
- `get_logs`: bounded redacted build/runtime logs
- `rollback`: activate a retained immutable release
- `configure_database`: explicit opt-in; never call by default

## Common CLI commands
```sh
rightside login --url https://api.rightside.host
rightside install claude
rightside install codex
rightside doctor --json
rightside deploy . --name my-app
rightside status my-app --json
rightside logs my-app --runtime
rightside rollback my-app
```

## Security contract
Never ask for or place tokens, passwords, one-time codes, cookies, session IDs, or database URLs in chat, source, argv, logs, images, or MCP registration. The local MCP registration contains the executable, operations origin, and credential-file path, not the bearer token. RightSide provides bounded deployment operations, not arbitrary remote shell access.

## Current support
Supported: Linux x64, x64 WSL2, Apple silicon macOS, Node.js 22.13+. Not supported: native Windows, Intel macOS, Linux ARM64, public signup. Default workload: database-free. CLI/MCP project creation enables hosted-app authentication; configure public paths or explicit auth:false/--no-auth when required. Persistence remains opt-in.