Self-hosted sync server for the Copper
browser. One Rust daemon (copper-cloud), one Postgres. Install it on any Linux VM with one
command, or deploy to AWS with Terraform (deploy/aws).
What it syncs between your Coppers: spaces + pinned tabs, settings (safe subset), bookmarks, history (append-only; people can delete theirs) and each device's open tabs. It can also hand every signed-in Copper the instance's AI keys (Jev + LLM router), set once by the admin, so nobody pastes keys by hand.
Shared canvases (live Yjs rooms, chat, mentions, invites, share links) are served by a linked
Canvas Cloud (since 0.11.0): copper-cloud
proxies the unchanged canvas API to it as the signed-in user, so Coppers need no update. See
docs/canvas-link.md; upgrading a 0.10.x (or older) instance with canvases:
docs/canvas-migration.md.
People who are not on Copper open shared canvases in any browser at https://HOST/canvas/
(Canvas App), and share links offer it too
(docs/canvas.md).
People can join with company single sign-on (Google Workspace or any OpenID Connect
provider): share one https://HOST/start page, they install Copper and click Continue with
Google — no account to create, no password (docs/sso.md). Agent
integrations let a trusted service pair headless Coppers (e.g. one per bot) to its owners'
accounts (docs/sso.md). The device agent relay lets an
agent (any MCP client) use a person's Copper for iOS while it is open on their screen, through
/v1/agent/mcp with a token the phone mints (docs/api.md).
curl -fsSL https://raw.githubusercontent.com/copper-browser/copper-cloud/main/install.sh | sudo shor from a release tarball:
tar xzf copper-cloud-0.13.1-linux-x86_64.tar.gz && sudo ./install.shThe installer sets up Postgres (unless you pass DATABASE_URL), a copper-cloud system user,
/etc/copper-cloud/copper-cloud.toml with fresh keys, a self-signed certificate (or Let's
Encrypt with COPPER_CLOUD_DOMAIN=…), a hardened systemd unit and a portal admin account,
then prints:
Admin portal: https://203.0.113.10/
email: admin@203.0.113.10
password: <24 chars> (shown once; also in /etc/copper-cloud/admin-credentials)
Access mode: directory
Link code for your first Copper (Settings › Cloud › Connect; creates one account):
copper-cloud://203.0.113.10:443/#k=ck_<access key>&fp=<certificate sha256>
Paste the link code into Copper › Settings › Cloud › Connect and create your account. To
let other people in, sign in to the admin portal and mint each person an access key
(Access keys › New key) — each comes with its own link code, revocable any time. A signed-in
Copper can also pair another Mac with a single-use pairing code. Choose the admin with
COPPER_CLOUD_ADMIN_EMAIL / COPPER_CLOUD_ADMIN_PASSWORD, or start in open mode (one shared
link code for everyone) with COPPER_CLOUD_ACCESS_MODE=open. Re-running the installer upgrades
in place and keeps keys, certificate, admins and data. Details: docs/install.md,
docs/operations.md.
For canvases, install a Canvas Cloud (the
small setup: same host, 127.0.0.1:8480, TLS off), create an app key there with
canvas-cloud apps create --name "Copper Cloud" --allow-import, and link it:
sudo copper-cloud canvas link --url http://127.0.0.1:8480 --key-file /root/canvas-app.keyUntil then canvas requests answer 503 canvas_unavailable and doctor warns. Details:
docs/canvas-link.md.
AWS (EC2 + RDS + Elastic IP; link code and admin password in SSM): see deploy/aws/README.md.
Needs Rust (stable) and a native PostgreSQL (createdb copper_cloud_dev).
cargo run -- init-config --write /tmp/cc.toml
COPPER_CLOUD_DATABASE_URL=postgres://localhost:5432/copper_cloud_dev \
cargo run -- --config /tmp/cc.toml serve
# another shell:
cargo run -- --config /tmp/cc.toml link-code # copper-cloud://localhost:8443/#k=…&fp=…
COPPER_CLOUD_DATABASE_URL=postgres://localhost:5432/copper_cloud_dev \
cargo run -- --config /tmp/cc.toml doctor
curl -k https://localhost:8443/healthz # ok
printf 'a dev admin password\n' | COPPER_CLOUD_DATABASE_URL=postgres://localhost:5432/copper_cloud_dev \
cargo run -- --config /tmp/cc.toml admin create-admin --email admin@example.com --password-stdin
open https://localhost:8443/ # admin portal (needs portal/out, see below)The admin portal is the Next.js app in portal/ (cd portal && bun install && bun run build
→ portal/out); debug builds serve portal/out from disk, release builds embed it.
init-config defaults to listen = 0.0.0.0:8443, public_url = localhost:8443, a
self-signed certificate in <config dir>/tls/ (created on first start) and Prometheus metrics
on 127.0.0.1:9464. Every config key can be overridden with COPPER_CLOUD_<KEY>
(COPPER_CLOUD_TLS__MODE=off for plain HTTP).
| Command | What it does |
|---|---|
copper-cloud [serve] |
run the server (applies migrations first; --no-migrate to skip) |
copper-cloud migrate |
apply database migrations |
copper-cloud link-code [--sso] |
print the link code (--sso: the single sign-on join link, no secret) |
copper-cloud doctor |
check config, database, migrations, TLS, listener, SSO, Canvas Cloud link |
copper-cloud healthcheck --wait 60 |
wait for /healthz (pinned TLS) |
copper-cloud tls-init [--force] [--name N] |
create the self-signed certificate |
copper-cloud init-config --write PATH |
write a config with fresh keys |
copper-cloud admin users|create-user|reset-password|delete-user|disable-user|enable-user|disable-signup|enable-signup |
user administration |
copper-cloud admin create-admin|reset-admin-password|list-admins|delete-admin |
portal admin accounts |
copper-cloud admin access-mode|set-access-mode open|directory|create-access-key |
who may pass the gate |
copper-cloud admin sso show|set-google|set-oidc|disable|enable|delete|password-signin on|off |
company single sign-on (client secret from stdin only, never shown) |
copper-cloud admin integration create|list|rotate|revoke |
agent-integration keys (cai_…, printed once) |
copper-cloud admin set-instance-name NAME |
the name on the /start onboarding page |
copper-cloud admin history delete --user EMAIL|UUID [--since T] [--until T] [--device ID] [--dry-run] |
delete (or count) a user's synced history wholesale, by time window/device only (never by content) |
copper-cloud intelligence set|show|clear|enable|disable |
cloud-wide Jev + LLM router keys every signed-in Copper receives (keys from files/stdin, shown masked), plus the org-wide agent round budget (--agent-max-turns, clear --agent) |
copper-cloud addons list|slots|upload FILE --slot SLOT|enable ID --everyone|--people a@x,b@y|disable ID|settings ID --json '{…}'|delete ID --yes |
addons: web bundles that replace a slot of the Copper window (e.g. the agent sidebar), handed to everyone or listed people (docs/addons.md); also copper-cloud admin addons … |
copper-cloud canvas link --url URL --key-file F [--fingerprint HEX] [--no-sync] |
link a Canvas Cloud (app key from a file/stdin, never argv) and provision every user |
copper-cloud canvas unlink|status|sync-users [--prune] |
remove the link / show it and test it / push every user now (--prune: also delete Canvas Cloud users that no longer exist here) |
copper-cloud canvas migrate [--dry-run] [--only ID]… [--replace] [--concurrency N] [--json] |
copy legacy canvases into the linked Canvas Cloud, verified by digest (docs/canvas-migration.md) |
copper-cloud version |
version |
All commands take --config PATH (default /etc/copper-cloud/copper-cloud.toml, env
COPPER_CLOUD_CONFIG).
- Architecture — components, data model, request path
- HTTP API — every endpoint with requests and responses
- Changelog — what changed in each release
- Admin API — the admin portal's
/admin/api/*contract - Addons — slot addons: manifest, bundles, who gets what, API, CLI, security
- Canvas link — how canvases are served by a linked Canvas Cloud: proxy, events, provisioning, linking, security
- Canvas migration — moving legacy canvases to Canvas Cloud (runbook, rollback)
- Canvas · Canvas protocol — pointers to the canvas API, now documented in Canvas Cloud
- Security — threat model, access keys, pairing, admin sessions, encryption at rest, TLS pinning
- Install — VM one-liner, manual install, configuration reference
- Operations — doctor, logs, metrics, backups, upgrades
- Onboarding a team — single sign-on first, link codes, people, keeping links valid
- Single sign-on + agent integrations — Google / OIDC setup,
/start, agent pairing - v0.13.1 release notes · v0.13.0 · v0.12.0 · v0.11.1 · v0.11.0 · v0.10.0 · v0.9.0 · v0.8.1 · v0.8.0 · v0.7.0 · v0.6.0 · v0.5.0 · v0.4.0 · v0.3.0
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
createdb copper_cloud_test_core # once
createdb copper_cloud_test_migrate # once, for crates/canvas-migrate
cargo test --workspaceTests use a real native Postgres (COPPER_CLOUD_TEST_DATABASE_URL, default
postgres://localhost:5432/copper_cloud_test_core; the migration tests use
COPPER_CLOUD_TEST_MIGRATE_DATABASE_URL, default
postgres://localhost:5432/copper_cloud_test_migrate); never a
container. The canvas-link tests run against an in-process mock Canvas Cloud. Releases: push a
vX.Y.Z tag matching the crate version; CI builds copper-cloud-X.Y.Z-linux-{x86_64,aarch64}.tar.gz
(+ .sha256) and publishes the GitHub release.
- Google SSO (TODO): sign in with Google (OIDC) as an alternative to email + password. Not implemented in v1; see docs/security.md.
- Master-key rotation (v1 documents a manual procedure only).