desk secrets

Available in Desk 0.3.0 and later. Install or update:

npm i -g @centillex/desk@0.3.0

Use Centillex Secrets to give an agent or task selected credentials for one approved launch. Configure access once for your project, then approve each retrieval when the task needs it.

Secrets is optional. You can pack and move work, list agents, and manage machines without a Secrets account, configuration, Google sign-in, or a connection to the Secrets service. Ordinary moves keep the harness’s existing authentication and environment.

Only desk secrets ..., desk org ..., desk project ..., or a move with --secrets=CAPABILITY uses the integration. If you request credentials and retrieval or approval fails, Desk stops that launch. It does not silently start the agent without the requested credentials.

Set up your first project

Run these commands from your local project root, in your own interactive terminal. You need an installed browser, a Google account, an authenticator app, and access to Centillex Secrets.

1. Connect your account:

   cd /path/to/devbox
   desk secrets check
   desk secrets onboard

   check tests public connectivity without credentials. In the setup window, sign in with Google, enter the displayed device code on the service page, and confirm your account. Save the recovery file outside your project. Desk reopens and verifies it, then asks you to scan the authenticator QR code and enter a fresh code.

2. Choose an organization and create a project:

   desk org ls
   desk project create devbox --org ORG_ID
   desk project ls --org ORG_ID

   Replace ORG_ID with an ID from org ls. Use the resulting project ID as PROJECT_ID below. You can use your personal organization or create another with desk org create NAME.

3. Save a secret document and connect the keys this project needs:

   desk secrets unlock

   Pair the local approval window with the Secrets dashboard, select your organization and project, and save an env document at /payments with an API_KEY field. Return to the same project directory and run:

   desk secrets connect --project PROJECT_ID --path /payments --name payments --keys API_KEY
   desk secrets ls

   connect creates a project agent and saves its local capability outside your repository. The capability named payments is bound to the current directory. Only the selected document keys can be supplied to a task.

4. Request credentials for your application or agent:

   desk secrets run payments --reason="Inspect devbox payment failures" -- ./report

   Replace ./report with your task executable. Desk prints an approval link and waits. Review the request in the dashboard, or use another terminal:

   desk secrets requests
   desk secrets approve --request REQUEST_ID

   Confirm the request and enter a fresh authenticator code. The task starts with API_KEY in its environment. The parent shell receives no credential.

   To supply the same capability when moving an existing pack:

   desk move --to=codex --secrets=payments --secret-reason="Continue devbox development"

   Pack the source agent’s work first; see desk pack. Each launch requires a new approval. Use desk secrets lock when finished.

Self-service account and project setup

Accounts join organizations; organizations contain projects; projects contain secret documents. An environment-variable bundle is a document type, not a separate environment in the hierarchy.

desk secrets onboard
desk org ls
desk org create centillex
desk project create devbox --org ORG_ID
desk project ls --org ORG_ID
desk secrets unlock
desk secrets lock

Onboarding opens a local setup window. Sign in with Google, enter the public device code on the service page, then return to Desk to confirm the account. Choose where to save a recovery file in the local file picker. Desk reopens the file and verifies recovery before activation. Scan the QR code in the local window and enter your authenticator code to finish. A personal organization is created automatically. Enrollment revokes any legacy agent keys on that account.

New identities need no passphrase. Desk derives an AES-256 wrapping key from two independent random components, one on the device and one held by the service. The service releases its component after the enrolled device proves its identity, you sign in with Google, and you enter a fresh authenticator code. The component is used in memory, never written into the device file. A local background process keeps the unlocked signing key for subsequent commands. Owner requests require both the owner signature and an active device signature.

Keep the recovery file in your password manager or on separate protected storage. It contains a restricted recovery credential, a local component, and the encrypted owner key; it does not contain the service component. Possession of this file plus Google sign-in can replace a lost authenticator. To recover, choose I have a recovery file in onboarding, save a replacement recovery file, and set up a new authenticator. Recovery revokes previous devices, recovery files, agent keys and sessions. Reconnect agents afterward. On a device with an existing profile, run desk secrets onboard and choose Recover with a saved file. Explicit onboarding locks any active local session before opening account setup; ordinary owner commands use the shorter unlock flow.

The local file picker is served by Desk and saves files directly with private permissions. Desk includes its setup pages, fonts, QR renderer, and approval window in the Go binary; no Node runtime or separate file-dialog utility is needed. Run onboarding from an interactive terminal in a desktop session with an installed browser. On macOS, Desk uses the system browser through open. On WSL, Desk uses Windows PowerShell to open the private setup file in your Windows browser through the WSL filesystem share. Enable Windows interoperability and keep the default localhost forwarding enabled. No wslview helper is needed. See Microsoft’s WSL networking guide for Windows browser access to a service running in WSL. If opening the browser fails, Desk reports the failure; correct the browser association and run onboarding again.

Native CI exercises Linux and macOS with synthetic accounts in Chromium and WebKit. This checks the embedded setup flow and recovery-file handling without using a real Google account. Live Google/service onboarding on macOS and WSL browser handoff remain separate acceptance checks. Device onboarding requires the corresponding service endpoints and custody configuration.

Use --account NAME on owner commands such as secrets onboard, org ls, project create, and secrets connect to keep separate local Google account profiles. secrets run and move --secrets use the selected capability instead. Owner keys and sessions live under ~/.desk/credentials/accounts/NAME. Older passphrase-based owner profiles are not automatically migrated or replaced. Device enrollment and its recovery file are required for the native owner commands. Google sessions expire after eight hours. After onboarding, commands such as desk org ls and desk project ls reuse the unlocked local session. It locks after 15 minutes without CLI activity, after one hour at most, or when you run desk secrets lock. The signing key stays in the background process’s memory; the private IPC descriptor on disk contains no owner seed or service component.

After the local session locks, the next command asks for an authenticator code. It reuses the saved Google session, so account linking, recovery-file saving and QR enrollment are not repeated. If the Google session has expired, sign in again before unlocking. The service must be online. If an activation response is lost, Desk checks its signed status. Preserve the device and recovery files and run onboarding again. If you used an earlier development build with a Node background session, Desk retires that session. The first owner command needs one authenticator code to start the Go session; account setup and QR enrollment are retained.

desk secrets unlock opens the local signer window for the browser dashboard. Pair it there, select your organization and project, and manage secret documents. The device approval window shares the background session, so CLI commands remain usable while it is open. Opening it keeps the session available until its one-hour limit. Closing the signer with its lock button, or running desk secrets lock, locks both. The background process runs the same Desk executable.

For CLI uploads, prepare a JSON object of string keys and values in a private file and directory outside the project (0600/0700):

mkdir -p "$HOME/.desk/credentials/uploads"
chmod 700 "$HOME/.desk/credentials/uploads"

Save your JSON document as payments.json in that directory using your editor or credential-management tool. Then run:

chmod 600 "$HOME/.desk/credentials/uploads/payments.json"
desk secrets put --project PROJECT_ID --path /payments --kind env --file "$HOME/.desk/credentials/uploads/payments.json"
desk secrets documents --project PROJECT_ID

Use --generation CURRENT_GENERATION when updating or archiving a document. connect creates a separate 30-day project agent and writes its project-bound capability outside the repository. --keys explicitly selects environment names mapped from the same document keys; reserved runtime variables are rejected. The agent has a private local unlock file for automated tasks. Access to the OS account therefore remains a trust boundary; the owner passphrase is not reused.

Approve through the dashboard or your terminal:

desk secrets requests
desk secrets approve --request REQUEST_ID

Approval displays the exact request, requires confirmation and a fresh authenticator code, and allows one retrieval. Each agent’s issuing member is its assigned approver. Other organization members do not automatically gain the ability to approve that member’s requests.

Membership commands operate on accounts that have already onboarded:

desk org members --org ORG_ID
desk org add-member member@example.com --org ORG_ID --role member
desk org remove-member ACCOUNT_ID --org ORG_ID

Owners can add admins, members and viewers. Admins can add members and viewers. Members can create projects, edit secrets and issue agents; viewers can list and read project secrets with MFA. Removing membership revokes that member’s agents in the organization and cancels outstanding approvals. This version does not include email invitations or organization ownership transfer.

Prerequisites and trust

The Secrets integration runs entirely in the Desk Go binary. Its local web servers, signing, device custody, agent transport, HTML, JavaScript, styles, fonts and Centillex logo are embedded. There are no runtime downloads, Node installation, sidecar application files, CDN assets or native file-dialog tools. It opens your system browser through the operating system’s browser launcher.

Desk still creates private account and agent credential files, a Unix socket, and a short-lived private HTML launcher used to open the browser without putting its local capability in process arguments. These are generated state, not files you need to install alongside the executable. Recovery files are saved separately at the location you choose.

Go 1.27 implements ML-DSA-65 signing; CIRCL implements X-Wing HPKE. The statically linked Go TLS client offers only TLS 1.3, AES-256-GCM and X25519MLKEM768, and verifies the negotiated connection before sending an HTTP request. Certificate and hostname verification remain enabled. No fallback is attempted.

Retrieval requires all of:

• An expiring, path-scoped service token bound to an enrolled PQ agent identity.
• That agent’s encrypted ML-DSA-65 keyfile and its unlock passphrase.
• An independently verified service identity pin, obtained through your operator’s trusted enrollment process. Desk does not discover or trust a new pin from the network.
• The exact owner subject used by the service’s PQ enrollment.
• Your dashboard approval with the required owner authentication.

Use desk secrets onboard and desk secrets connect to prepare these materials. Desk cannot turn an ordinary bearer token into a PQ identity. Existing provider API keys are stored values; Desk does not issue temporary provider credentials.

Configure project capabilities

The configuration always lives at ~/.desk/credentials/secrets.json, independent of DESK_HOME. Keep it and every credential file outside the project and pack store. Use a private directory (0700) and regular private files (0600); credential-file symlinks are rejected.

Capabilities match the canonical local project directory. On another machine, onboard there and run desk secrets connect from the destination project. Packs do not transfer the account profile or project-agent credentials.

desk secrets connect creates this configuration for you. Manual editing is useful when you need to map document keys to different environment names. The example below contains references only. Substitute your canonical project path and enrolled owner subject, and use credentials from a trusted enrollment process. Keep credential values out of agent chat.

{
  "schema": 1,
  "capabilities": {
    "payments-read": {
      "description": "Read staging payments for devbox",
      "project": "/home/you/devbox",
      "path": "/staging/payments",
      "kind": "env",
      "tokenFile": "devbox-agent.token",
      "environment": { "PAYMENTS_API_KEY": "API_KEY" },
      "pq": {
        "keyFile": "devbox-agent.key.json",
        "passphraseFile": "devbox-agent.passphrase",
        "servicePinFile": "service-identity.json",
        "ownerSubject": "YOUR_ENROLLED_OWNER_SUBJECT"
      }
    }
  }
}

Relative credential paths resolve against the configuration directory. An old node property is ignored; no runtime executable is selected from configuration or PATH. environment maps child environment names to document keys. Both kv and env documents work. Only explicitly mapped values reach the child; a missing mapping or wrong document kind prevents launch.

Treat passphrase files as credentials. File permissions and encryption do not isolate credentials from other programs running as the same OS user. For hostile agents, use a separate OS identity or sandbox and a constrained broker.

Commands and rotation

Command	Behavior
secrets onboard [--account NAME]	Connects an account with Google, a recovery file, and an authenticator. Also provides recovery for an existing account.
secrets unlock [--account NAME]	Unlocks the owner session when needed and opens the local approval window.
secrets lock [--account NAME]	Closes the owner session and approval window.
secrets documents --project ID	Lists the project’s stored documents.
secrets put --project ID --path PATH --file FILE [--kind env] [--generation N]	Creates or updates a document from a private JSON file. Updates require its current generation.
secrets archive --project ID --path PATH --generation N	Archives the document at the specified generation.
secrets connect --project ID --path PATH --name NAME --keys KEY1,KEY2	Creates a project agent and a local capability for the current directory.
secrets requests	Lists the owner’s pending agent requests.
secrets approve --request ID	Reviews one request and approves one retrieval with confirmation and MFA.
secrets ls	Lists this project’s configured names, types and descriptions. Reads no secret values or token contents. This is local capability discovery, not server-side catalog authorization.
secrets check	Checks public connectivity using the strict transport. Requires no token and works before configuration exists. Does not test owner enrollment, PQ service identity or backend readiness.
secrets run NAME --reason TEXT -- COMMAND [ARGS...]	Requests approval, retrieves once, and starts a foreground task with selected environment variables.
move --secrets NAME	Retrieves immediately before starting the prepared target agent.

Organization and project commands use the same owner session:

Command	Behavior
org ls	Lists your organizations.
org create NAME	Creates an organization.
org members --org ID	Lists organization members.
org add-member EMAIL --org ID [--role ROLE]	Adds an already onboarded account with a permitted role.
org remove-member ACCOUNT_ID --org ID	Removes a non-owner member.
project ls --org ID	Lists projects in the organization.
project create NAME --org ID	Creates a project.

Prefix these commands with desk. Owner commands accept --account NAME; local discovery, connection checks, and task retrieval do not use that flag.

Approval instructions and the dashboard link go to stderr; Desk never prints retrieved values, tokens or key material. The task’s stdout/stderr are passed through, so a task that prints its credential can disclose it. Command arguments are ordinary arguments, not a place to supply secret values.

Each invocation obtains the service-approved document version. A rotated value is therefore available to the next approved task or launch. A running process’s environment does not change. Approval expiry does not expire a provider key; revocation must occur at the provider. A task that backgrounds children can leave credential-bearing processes running, so keep these tasks in the foreground.

Desk preserves an explicit baseline of terminal/home/runtime environment settings and drops ambient credentials and runtime injection options. Reserved mappings such as PATH, HOME, NODE_OPTIONS, LD_PRELOAD, proxy and CA override variables are rejected. Existing agent login files remain accessible under its normal HOME.

Denial, timeout, invalid signatures/pins, missing variables, transport failure or uncertain redemption prevents launch. Desk does not retry retrieval or redemption automatically. Reconcile the request in the dashboard before making another one.

Security scope

Quantum-safe credential exchange is a design goal from day one. Desk’s Secrets integration builds post-quantum key exchange and application signatures into the credential path, alongside AES-256 encryption and explicit owner approval.

The credential path requires TLS 1.3, X25519MLKEM768 and AES-256-GCM, with normal certificate verification and no redirects or classical fallback. Application requests use ML-DSA-65 signatures; encrypted requests and responses use X-Wing/AES-256 envelopes and verify the independent service pin. Encrypted agent keyfiles use scrypt/AES-256. Bearer-only retrieval is disabled.

These protections apply to Desk’s credential exchange. TLS certificates still use classical cryptography, supplemented by post-quantum application identity. Security across the full system also depends on account activation, trusted software distribution, owner authorization, backend storage and custody, and the destination API; each requires its own security assessment.

Access leases, constrained API proxying, provider-issued temporary credentials, automatic renewal and transparent hot rotation are future work. Desk 0.3.0 provides fresh approval-based retrieval and process injection.