Hosted agents, containers and CI
Overview
uc-storefront runs anywhere Node.js 24 runs, including containers and hosted agent platforms. Two things differ from a desktop: there is usually no OS credential store for the sign-in, and nobody is at the terminal to answer prompts. This page covers both, plus pinning the CLI for a team and checking it in CI.
Run on a hosted or containerized agent
Containers and hosted agents (for example Hermes Agent, Grok Bot, Fly.io machines and Docker containers) usually have no keychain. There the CLI keeps the sign-in in an encrypted file, using a key that a person stores in the platform's secret store as ULTRACART_STOREFRONT_CREDENTIAL_KEY. The CLI uses the encrypted file only when no OS credential store exists; where one exists, it ignores the key.
The platform has to pass that secret to the agent's shell commands as an environment variable. Where it can't, the hosted sign-in isn't possible yet.
| Platform | How the key reaches the CLI | Status |
|---|---|---|
| Desktop (macOS, Windows, Linux with Secret Service) | Not needed: the OS keychain holds the sign-in | Works |
| Grok Bot, Team Bot (Team or Enterprise plan) | The Bot's Secrets, with the environment variable name ULTRACART_STOREFRONT_CREDENTIAL_KEY | Documented |
| Grok Bot, Personal Bot | The masked secure secret card | Being tested: run auth status before signing in |
| Hermes Agent | ~/.hermes/.env on the host, with the name in terminal.env_passthrough | Documented |
| Fly.io | fly secrets set, with the configuration on a mounted volume | Documented |
| Docker | An env file passed with --env-file, with the configuration on a named volume | Documented |
| Muse (Meta) | None documented: no way to pass a saved secret to the agent's commands | Not possible yet |
The key is a secret, and anything an agent runs or reads can end up in its transcript. A person creates the key and stores it. Never paste it into an agent's chat, put it on a command line or in a project file, or ask an agent to create or read it. If the key or a token ever appears in a chat, create a new key, replace the secret, revoke the CLI's authorized application in UltraCart, and run auth login again.
1. Create and store the key
The key is 32 random bytes, base64 encoded. Use a method that never displays it:
-
Fly.io:
fly secrets set ULTRACART_STOREFRONT_CREDENTIAL_KEY="$(openssl rand -base64 32)" -
Docker: write it to an env file outside any project, restrict it, and pass it with
--env-file:printf 'ULTRACART_STOREFRONT_CREDENTIAL_KEY=%s\n' "$(openssl rand -base64 32)" > ~/.uc-storefront-key.envchmod 600 ~/.uc-storefront-key.env -
Hermes Agent: add
ULTRACART_STOREFRONT_CREDENTIAL_KEY=<key>to~/.hermes/.envon the host with an editor (or a secret-source plugin), and list the name interminal.env_passthroughinconfig.yaml. -
Grok Bot: on your own computer, put a key on the clipboard:
- macOS:
openssl rand -base64 32 | pbcopy - Linux:
openssl rand -base64 32 | xclip -selection clipboard - Windows PowerShell:
$b = New-Object byte[] 32; [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b); [Convert]::ToBase64String($b) | Set-Clipboard
Then paste it into a secret, never the chat:
- On a Team Bot, open Secrets, choose Add secret, and use
ULTRACART_STOREFRONT_CREDENTIAL_KEYas the environment variable name. - On a Personal Bot, ask the Bot to request the secret with the secure secret card.
See Grok Bot walkthrough.
- macOS:
uc-storefront auth keygen also prints a key, but only to an interactive terminal. Run it yourself, never through an agent.
2. Keep the configuration on persistent storage
If the home directory does not survive restarts, set ULTRACART_STOREFRONT_CONFIG_DIR to a persistent folder, the same in every session: a mounted volume on Fly.io or Docker, or a folder under /workspace on Grok Bot. Profiles and the encrypted sign-in (credentials/*.enc) live there. Keep it outside any project folder you might commit or share. Restart the session or container so the CLI sees the secret.
3. Check the key and sign in
uc-storefront auth status
uc-storefront auth login --profile my-store
uc-storefront auth status
The first auth status should show credential store: encrypted-file (durable, available) and credential key: set. It never shows the value. Until a profile exists and, inside a workspace, is bound with profile bind, the command also refuses and exits 1. The refusal is no profiles are configured, or inside a workspace workspace binding: missing. That's expected. Read the credential lines anyway. Inside a workspace, run profile bind before you confirm the sign-in with auth status, or pass --profile.
credential key: absentmeans the secret isn't reaching the shell. Check the secret's name, then start a new session. If the platform can't pass secrets to shell commands, sign-in isn't possible there yet.credential key: invalidmeans the value isn't a 32-byte base64 key. Replace it with a new key.credential key: setnext to a keychain store (macos-keychain,windows-credential-managerorlinux-secret-service) means the machine has a keychain, and the key is ignored.
auth login prints a URL and code, and the person approves the sign-in in their own browser. In 0.2.0-beta.3, auth login prints the URL and code first, then keeps running until the sign-in is approved. Many agents' command tools show output only when a command ends. If an agent's tool can't show the code before the command ends, the agent should tell the person that its platform can't relay the sign-in code yet.
Afterwards, auth status shows credential store: encrypted-file and local grant: present.
Use one sign-in per bot or container. Do not copy the configuration folder between machines: a renewal by one copy signs the other out. A new key makes the saved sign-in unreadable, which is expected; run auth login again.
Grok Bot walkthrough
Grok Bot gives each user one cloud computer. Every Bot on the account shares it, so files and command-line credentials are visible to all of them. Files under /workspace survive updates, Recover and Reset. Installed packages don't. Plan for both.
-
Create the key on your own computer with one of the commands in step 1. Each one puts the key straight onto the clipboard without showing it.
-
Give it to the Bot as a secret.
-
Team Bot: open Secrets, choose Add secret, and enter:
- environment variable name:
ULTRACART_STOREFRONT_CREDENTIAL_KEY - description:
UltraCart StoreFront CLI sign-in key. Never print or echo it. - value: paste from the clipboard.
Then choose Save secret. Everyone who chats with a Team Bot can use its secrets.
- environment variable name:
-
Personal Bot: ask the Bot to request a secret named
ULTRACART_STOREFRONT_CREDENTIAL_KEYwith the secure secret card, and to make it available to its shell commands as an environment variable. Paste the key into the card and choose Save securely.
Copy something else afterwards so the key doesn't stay on your clipboard.
-
-
Have the Bot install and check. In every command, the Bot puts
/workspace/.npm-global/binonPATHand setsULTRACART_STOREFRONT_CONFIG_DIRto a folder under/workspace. It installs with:npm install -g --prefix /workspace/.npm-global @ultracart/storefront-cli@beta --@ultracart:registry=https://registry.npmjs.org/It reruns that after an update, Recover or Reset. It then runs
uc-storefront auth statusand needscredential key: set.- If it shows
absent, the secret isn't reaching the Bot's shell. Stop and report it. Don't work around it.
- If it shows
-
Approve the sign-in. The Bot runs
uc-storefront auth login --profile mainand sends you the URL and code. Open the URL in your own browser, check the code, and approve. Never give the Bot your UltraCart password, and don't let it open the page. -
Confirm.
auth statusshowscredential store: encrypted-file (durable, available),local grant: presentandcredential key: set, and shows the same in a new session.uc-storefront sf storefrontslists your storefronts.
The Bot must never print the environment (env, printenv, echo $VAR), never run uc-storefront auth keygen, and never open or upload the credentials folder. A second Bot gets its own configuration folder, key and sign-in.
When the platform can't pass a secret to the shell
Some hosted agents keep saved secrets away from the commands they run. There auth status shows credential key: absent no matter what the person saves, and auth login refuses with no OS keychain is available here. Sign-in isn't possible on such a platform yet.
As of November 2026, Muse (Meta) is in this group: there is no documented way to pass a saved secret to the agent's shell commands.
Don't work around it. Never paste the key into the chat, a command or a file the agent can read. Offline commands (init, cjson, validate, tree, inspect) still work without signing in. For remote commands, use a desktop agent or a container whose secrets you control.
Bake the CLI and skill into the image
Install the CLI and create the workspace with its skill when you build the image, so every agent session starts ready. Name the agent target and pass --no-input, because a build cannot answer prompts:
npm install -g @ultracart/storefront-cli@beta
uc-storefront init /workspace/my-storefront --target codex --no-input
uc-storefront --workspace /workspace/my-storefront skills status --check
Never bake the credential key, the configuration directory or a sign-in into the image. The person signs in once the container is running, as in Check the key and sign in, and the sign-in stays on the persistent volume.
Pin the CLI for a team
For a team or CI, add the CLI as an exact project dependency instead of a global install, and commit package.json and the lockfile:
npm install --save-dev --save-exact @ultracart/storefront-cli@<version>
npm exec -- uc-storefront --version
npm exec -- uc-storefront init --target codex --no-input
npm exec -- uc-storefront skills install
npm exec -- uc-storefront skills status --check
Use npm ci in CI. Use the same invocation, here npm exec -- uc-storefront, for every command in the project, including skill refresh.
Script it
- JSON output. Every command accepts
--json(an alias for--format json), before or after the subcommand. Output is one JSON result or error, with no prompts or progress on stdout. - No prompts.
initandskills installtake--no-input. Without a saved or named target, a non-interactiveinitrefuses withtargets_required. - Errors. A JSON error has the shape
{ "formatVersion": 1, "error": { "code": "...", "message": "...", "paths": [] } }. Branch onerror.code, never on the message text. A refusal from UltraCart's server addserror.serverwith its ownstatusandcode. - Exit codes.
0is success.1is an operational failure.2is invalid arguments, configuration, a conflict or a refused downgrade.3meansskills status --checkfound drift, or a command is waiting on an approval or secret request. - Skill drift in CI.
uc-storefront skills status --checkexits3when installed skill files are missing, edited, or from another version. - One command at a time. UltraCart limits concurrent requests per IP address, whatever profile each command uses. It also applies hourly and daily call limits, both for this machine's calls to the account (shared by every sign-in and tool on it) and for this sign-in from every machine. Run remote commands one at a time and do not retry in a loop. On HTTP 429 (
rate_limited), the error names the limit and how long to wait (retryAfterSeconds); wait at least that long before sending one more command.
One workspace per merchant
An automated runner that serves several merchants needs one workspace per merchant, each bound to its own profile. A workspace with an ultracart.json file never falls back to another workspace's binding or a default profile, so a job cannot write to the wrong store because of where it ran. See One workspace per merchant.
Related documentation
- Connect your store: profiles, sign-in and credential storage
- Troubleshooting:
credential_store_unavailableand other setup errors - Safety and human approval: approvals an automated agent still waits for