> ## Documentation Index
> Fetch the complete documentation index at: https://opensandbox-docs-ask-context.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets and runtime variables

> Configure managed outbound credentials and agent runtime environment variables

OpenComputer secrets are write-only values used by declared outbound
connections. Plaintext values are not included in source bundles, prompts,
deployment manifests, runtime environment variables, logs, or API responses.

<Note>
  Some credentials are not secrets you set. When someone connects their Gmail,
  Calendar, Drive or Sheets account, the platform holds and refreshes that
  credential — see [Connected services](/agents/services).
</Note>

## Declare a connection

```tsx theme={null}
import { bearer, defineConnection, useSecret } from "@opencomputer/agent";

const github = defineConnection({
  id: "github-api",
  origin: "https://api.github.com",
  methods: ["GET"],
  pathPrefix: "/repos/",
  headers: {
    Authorization: bearer(useSecret("GITHUB_TOKEN")),
  },
});

export default function Agent() {
  return "Use GitHub when it helps answer the request.";
}
```

The origin must use HTTPS. OpenComputer rejects hard-coded sensitive headers
such as `Authorization`, `Cookie`, and `X-API-Key`; reference a managed secret
instead.

Tools can make requests through the same connection:

```tsx theme={null}
const response = await github.fetch("/repos/opencomputer/example");
const repository = await response.json();
```

Only a relative path is accepted. OpenComputer checks the declared origin,
path prefix, method, agent, and environment before sending the outbound
request.

## Synchronize development secrets

Place development-only values in `opencomputer/.env.local`:

```dotenv theme={null}
GITHUB_TOKEN=github_pat_...
```

`opencomputer doctor` compares these local names with `useSecret()` references
and `.env.example`. Upload is always explicit; deployment never opens a value
prompt. The CLI infers the allowed origins from the source declaration.

Variables without a matching declaration are skipped. OpenComputer never
grants an unmatched value access to every host, and removing a local variable
does not delete its cloud value. Use `opencomputer secrets remove` when deletion
is intentional. The starter ignores `opencomputer/.env.local` and includes an
`opencomputer/.env.example` file for documenting required names without values.

## Set a project secret

Secrets belong to a cloud project. Link explicitly first with
`opencomputer link --project <id|slug>` or `--create-project <name>`.

```bash theme={null}
printf %s "$GITHUB_TOKEN" | npx --package @opencomputer/cli opencomputer secrets set GITHUB_TOKEN --value-stdin
```

The CLI accepts the value only from piped standard input. When run from an
initialized project it infers allowed origins from connections that reference
the secret.

Project secrets are available to declared connections in every agent in the
project. Create an agent-specific override when one agent needs a different
credential:

```bash theme={null}
printf %s "$GITHUB_TOKEN" | npx --package @opencomputer/cli opencomputer secrets set GITHUB_TOKEN --value-stdin --agent current
```

Secrets are separate for `development` and `production`:

```bash theme={null}
printf %s "$GITHUB_TOKEN" | npx --package @opencomputer/cli opencomputer secrets set GITHUB_TOKEN --value-stdin --environment production
npx --package @opencomputer/cli opencomputer secrets list --environment development
npx --package @opencomputer/cli opencomputer secrets remove GITHUB_TOKEN --environment development
```

List output contains metadata such as the name, scope, environment, and
allowed origins. Secret values are never returned.

## Agent runtime variables

Use an agent runtime variable when code or a command must receive a value as a
normal environment variable. Configure it in the **Agent runtime variables**
section of the project's Secrets page, or with the CLI:

```bash theme={null}
printf %s "$DATABASE_URL" | npx --package @opencomputer/cli opencomputer env set DATABASE_URL --value-stdin
npx --package @opencomputer/cli opencomputer env list --environment development
npx --package @opencomputer/cli opencomputer env remove DATABASE_URL
```

The CLI reads new values only from piped standard input. Runtime variables can apply to
the whole project or override one agent with `--agent current`, and development
and production values are separate. No declaration in agent source is needed.

OpenComputer stores these values encrypted and never returns them through the
dashboard or management API. A newly started agent runtime receives the
resolved values in its process environment, so agent code, tools, commands, and
child processes can read them. Because the agent can access the plaintext,
runtime variables are appropriate for personal-agent credentials such as
`DATABASE_URL`, but they do not provide the destination isolation of managed
secrets. Restart a running agent runtime after changing a value.

## Security guarantees

For managed secrets, OpenComputer resolves the declared connection and scoped secret for each
request. The credential is attached only after the destination, method, path,
agent, project, and environment have been validated. The value is never added
to the agent's source bundle, prompt, browser application, or logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.