Hosted APIs

Every Anycloud command talks to one active API. A local API runs in Docker on your machine. A hosted API runs as a long-lived Service in your cloud account and has a stable public URL, so you can use it from multiple machines or share it with trusted teammates.

	Local API	Hosted API
Start or create	anycloud api start	anycloud api serve
Reachability	Loopback-only by default	Public URL; operations require GitHub login
State	~/.anycloud/api.db and ~/.anycloud/cipher.key	Dedicated, user-owned checkpoint bucket
Lifecycle manager	Local Docker	Local API that created the hosted Service

Hosting changes where the API runs; it does not create tenant isolation. Everyone admitted to one hosted API shares its operational resources and trust boundary.

A hosted API binds its restored database to the stable Service deployment ID. Its backing VM can change without changing that identity, but restoring the database under a different hosted deployment is rejected. To read or recover such a checkpoint, copy its api.db and cipher.key into ~/.anycloud and start a local API, which takes on the database as it finds it.

Create a hosted API

The local API that creates a hosted API remains its lifecycle manager. Keep the local ~/.anycloud state that contains the hosted Service deployment record; you need that manager to update or retire the hosted API later.

Start the local API if it is not already running, then make it active:

anycloud api start
anycloud api use local

Create or select a cloud credential, then create one dedicated bucket for the hosted API's database and encryption key:

anycloud bucket create my-api-state \
  --credentials my-aws \
  --region us-east-1

Deploy the hosted API through the local API:

anycloud api serve \
  --id team-api \
  --credentials my-aws \
  --vm-type t3.small \
  --checkpoint-bucket my-api-state \
  --use

The example leaves --region unset so Anycloud can fail over between eligible compute regions. The region used to create the bucket identifies its storage location; it does not need to pin the hosted API's compute.

api serve waits for the Service and its API endpoint to become healthy. The --use flag then saves the new URL as the active API. Without --use, the command prints the URL and the command needed to select it. --use cannot be combined with --no-wait because an API must be healthy before it becomes the saved target.

Cluster creation requires an active hosted API. The credential passed to api serve selects the control-plane host cloud. The credential passed later to cluster create selects cluster capacity independently. See Clusters for the complete flow.

The checkpoint bucket must already exist. By default, the selected compute identity must have read-write access to it. Compute providers without compatible object storage can instead use a separate AWS identity:

anycloud api serve \
  --credentials lambda-compute \
  --vm-type cpu_4x_general \
  --checkpoint-bucket my-api-state \
  --checkpoint-storage-credentials aws-storage \
  --checkpoint-storage-region us-east-1 \
  --use

Anycloud validates the bucket before creation, replacement, and termination but never creates, recreates, or deletes it. The hosted API is the only Service that accepts separate checkpoint credentials. See Buckets for state sync and crash-consistency behavior.

Select an API

List the APIs discoverable through the local manager and show the active one:

anycloud api list
anycloud api info

Switch by hosted deployment ID, public URL, or the local alias:

anycloud api use team-api
anycloud api use https://team-api.anycloud.sh
anycloud api use local

Running anycloud api use without a target opens a picker of healthy, compatible APIs in an interactive terminal. The saved target lives in ~/.anycloud/api-url; API_URL overrides it for one command.

Give someone access

A hosted API initially accepts only the GitHub account that created it. Anyone with access can add or remove other GitHub users, without requiring everyone to belong to the same GitHub organization.

Only add people you trust with the API's cloud access. Everyone with access is an equal peer. They can use credentials and secrets, inspect the database, manage spend controls, and operate everyone else's workloads just as they can their own. There is no admin role inside the hosted API. The account that created it still controls the hosted Service through the separate local API that deployed it, including replacing or terminating that Service.

First make the hosted API the active target, then add a GitHub username:

anycloud api use https://team-api.anycloud.sh
anycloud api access add octocat

Anycloud resolves the supplied username to GitHub's immutable account ID and stores that ID in the hosted API. A later username change does not remove the person's access, and a different account that acquires the old username does not inherit it. Only individual GitHub user accounts can be added; passing an organization name is rejected, since an organization cannot sign in.

Because access is peer-to-peer, anyone you add can add or remove other members. Treat adding someone as handing over the API, not lending it. The account that created the hosted API cannot be removed.

List everyone with access at any time:

anycloud api access list
anycloud api access list --json

The access commands always operate on the active API shown by anycloud api info, and only apply to a hosted API — on a local API they report that sharing is unavailable.

Connect as a teammate

The teammate authenticates with their own GitHub account and selects the URL shared with them:

anycloud login
anycloud api use https://team-api.anycloud.sh
anycloud api info
anycloud list

No invitation token or organization check is involved. The GitHub account used by anycloud login must be the same account that was added.

What is shared

Resource or capability	Behavior
Jobs, Services, and VMs	Shared API-wide; anyone can operate on any creator's workload when its type and state support it
Quota operations	Shared API-wide
API access list	Anyone with access can read it and add or remove non-owner members
Cloud credentials and named secrets	Shared; anyone can use and manage them
Spend controls	Shared API-wide; alerts attribute multi-account waiting and budget spend
anycloud db inspection	Read-only, but covers the API-wide database rather than only the caller's rows

anycloud list covers everyone's deployments on a shared API. When the returned rows include another account's work, it adds a USER column naming who created each one, even if that account is the only creator in the result. Narrow to one person with --user; the interactive summary also offers "by user" when several creators are present. Agent invocations continue to scope themselves to their own session automatically, so parallel agents still do not see each other's work.

anycloud list --user octocat
anycloud cost --user octocat

anycloud cost reports the whole API's spend and breaks it down per user, so a shared total is never mistaken for one person's. The breakdown appears even when one teammate accounts for the entire result and is omitted only when all reported spend belongs to the caller.

The GitHub account that created each workload is recorded permanently and is never rewritten.

This is a trusted-team access model, not tenant isolation. If users need separate credentials, secrets, or administrative boundaries, run separate hosted APIs.

Remove access

Remove a member by the GitHub username or immutable account ID shown by the access list:

anycloud api access remove octocat
anycloud api access remove 583231

Removal blocks the account's next authenticated request, including when its GitHub identity was already cached. A request admitted before removal may still finish.

Removal does not stop or transfer work the member already submitted. Queued, running, retrying, and cleaning workloads continue to be managed by the hosted API, retain their original creator attribution, and remain visible and terminable by every remaining member. Review them deliberately after removal:

anycloud list --user 583231

Deployments belong to the hosted API; membership only controls who can reach that API. This separation prevents a departing member's live workloads from becoming orphaned and continuing to spend without anyone being able to stop them.

Removing API access cannot revoke copies of cloud credentials or named secrets the member may already have seen. Rotate sensitive shared credentials and secrets as part of security-related offboarding.

GitHub organization membership is not consulted, so removing a person from an organization does not affect their Anycloud access.

Update a hosted API

Update the CLI first, then reconcile the local-to-hosted control chain:

anycloud update
anycloud api update

With a hosted API active, api update updates or starts the local manager and then finds the hosted Service in that local API's database. It replaces the backing VM with the API image matching the installed CLI while preserving the public URL and checkpoint state. The endpoint has downtime during replacement.

The active target does not change. A machine whose local API does not contain the hosted deployment record cannot update it. Hosted APIs created without a retained checkpoint bucket cannot be updated safely and must be redeployed with anycloud api serve.

Retire a hosted API

First use the hosted API to review and terminate workloads that should not continue running:

anycloud api use https://team-api.anycloud.sh
anycloud list
anycloud terminate <workload-id>

Then return to the local manager and terminate the hosted Service itself:

anycloud api use local
anycloud terminate team-api
anycloud status team-api --watch

Termination stops the hosted API and completes a final checkpoint upload before removing its VM. Check anycloud status team-api --json and wait for deployment.cleanedAt before deleting the state bucket. Bucket deletion is separate and permanently removes the hosted API's retained database and key:

anycloud bucket delete my-api-state \
  --credentials my-aws \
  --region us-east-1

anycloud api stop stops only the local Docker API; it does not stop a hosted API. To replace the original owner or rotate the entire trust boundary, deploy a fresh hosted API and retire the old one.

Troubleshooting

• Run anycloud api info and confirm the intended hosted URL is active.
• Run anycloud api list through the local manager to confirm it still has the hosted Service deployment record.
• Run anycloud login again if a teammate authenticated with a different GitHub account.
• Confirm an access entry with anycloud api access list.
• Update the CLI and hosted API if a CLI/API version mismatch is reported: anycloud update, then anycloud api update.

See api and utilities for exact command syntax and options.