Authenticate the Celesto SDK and CLI

Celesto uses an API key to identify your project and authorize SDK or CLI requests. You can save the key once for CLI commands, set it in your environment for SDK code, or pass it directly when you create a computer client.

Save your key for the CLI

If you use the celesto CLI, save your key one time and reuse it for every command:

celesto auth login

The command prompts for your API key and stores it in your operating system’s secure credential store: Keychain on macOS, Credential Manager on Windows, or Secret Service on Linux. Manage the saved key with:

celesto auth status
celesto auth logout

The saved key is scoped to the Celesto API URL. If you point the CLI at a different environment with --base-url or CELESTO_BASE_URL, sign in again for that URL.

API key lookup order

The CLI resolves the API key in this order:

--api-key flag
CELESTO_API_KEY environment variable
.env file in the current directory
Key saved by celesto auth login

Verify which credential a command uses

Each API key is bound to a single organization. Because the lookup order reads .env from the current working directory, the same command can target a different organization depending on where you run it. Run celesto auth status to see exactly which key and organization CLI commands use from your current directory:

celesto auth status
# API URL:      https://api.celesto.ai/v1
# Credential:   your saved login (system keyring)
# Organization: Acme Research (org_123)

The output reports:

API URL: the endpoint commands target. Pass --base-url to check the credential saved for a different environment.
Credential: the exact source the key came from, such as the CELESTO_API_KEY environment variable, a .env file, or your saved login.
Organization: the organization the resolved key is bound to.

When a .env file in the current directory holds a different key than your saved login, celesto auth status names both organizations and tells you how to switch. Every other CLI command prints a one-time warning on stderr in that situation, naming the .env file that overrides the saved login. The warning goes to stderr, so --json output on stdout stays parseable. To use your saved login instead of the .env key, run the command from another directory or pass --api-key explicitly. Destructive commands also name the organization they act on: celesto computer delete includes it in the confirmation prompt, and celesto computer stop includes it in the result message. --force and --json skip the organization lookup, so scripted calls make no extra request.

Choose credentials for Python

CloudComputer checks these sources in order:

api_key= passed in code
CELESTO_API_KEY in the process environment
The key saved by celesto auth login

Load a .env file into your environment yourself if you use one; the Python cloud client reads the process environment directly. An environment key takes precedence over a successful saved CLI login.

Set the required permissions

Named API keys work with CloudComputer. Choose permissions for the actions your application needs:

Permission	Actions
See your computers (`computers:read`)	Inspect computers and their state.
Create, start, stop computers and run commands (`computers:exec`)	Create, run, stop, resume, and connect to a computer.
Delete computers (`computers:admin`)	Delete computers. Required for automatic cleanup with `with CloudComputer()`.

The key’s owner also needs access to its organization. A valid key can still be rejected when its permission or the owner’s membership is missing; the error message identifies the required change.

Use an environment variable

export CELESTO_API_KEY="your-api-key"

Create a computer, run a command, and delete it on exit:

auth.py

from celesto import CloudComputer


with CloudComputer() as computer:
    print(computer.run("uname -a").stdout)

Pass the key in code

Pass api_key when you need to select credentials explicitly:

auth_explicit.py

import os

from celesto import CloudComputer

with CloudComputer(api_key=os.environ["CELESTO_API_KEY"]) as computer:
    print(computer.run("uname -a").stdout)

Both examples create a computer. Check the quickstart for trial limits before running them.

Get started

Run code

Save and resume work

Connect your apps

Connect AI agents

Reference and troubleshooting

Authenticate the Celesto SDK and CLI

Save your key for the CLI

API key lookup order

Verify which credential a command uses

Choose credentials for Python

Set the required permissions

Use an environment variable

Pass the key in code

​Save your key for the CLI

​API key lookup order

​Verify which credential a command uses

​Choose credentials for Python

​Set the required permissions

​Use an environment variable

​Pass the key in code

Save your key for the CLI

API key lookup order

Verify which credential a command uses

Choose credentials for Python

Set the required permissions

Use an environment variable

Pass the key in code