Skip to main content
How-to

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.

PlatformHow the key reaches the CLIStatus
Desktop (macOS, Windows, Linux with Secret Service)Not needed: the OS keychain holds the sign-inWorks
Grok Bot, Team Bot (Team or Enterprise plan)The Bot's Secrets, with the environment variable name ULTRACART_STOREFRONT_CREDENTIAL_KEYDocumented
Grok Bot, Personal BotThe masked secure secret cardBeing tested: run auth status before signing in
Hermes Agent~/.hermes/.env on the host, with the name in terminal.env_passthroughDocumented
Fly.iofly secrets set, with the configuration on a mounted volumeDocumented
DockerAn env file passed with --env-file, with the configuration on a named volumeDocumented
Muse (Meta)None documented: no way to pass a saved secret to the agent's commandsNot possible yet
warning

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.env
    chmod 600 ~/.uc-storefront-key.env
  • Hermes Agent: add ULTRACART_STOREFRONT_CREDENTIAL_KEY=<key> to ~/.hermes/.env on the host with an editor (or a secret-source plugin), and list the name in terminal.env_passthrough in config.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_KEY as the environment variable name.
    • On a Personal Bot, ask the Bot to request the secret with the secure secret card.

    See Grok Bot walkthrough.

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: absent means 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: invalid means the value isn't a 32-byte base64 key. Replace it with a new key.
  • credential key: set next to a keychain store (macos-keychain, windows-credential-manager or linux-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.

  1. 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.

  2. 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.

    • Personal Bot: ask the Bot to request a secret named ULTRACART_STOREFRONT_CREDENTIAL_KEY with 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.

  3. Have the Bot install and check. In every command, the Bot puts /workspace/.npm-global/bin on PATH and sets ULTRACART_STOREFRONT_CONFIG_DIR to 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 status and needs credential key: set.

    • If it shows absent, the secret isn't reaching the Bot's shell. Stop and report it. Don't work around it.
  4. Approve the sign-in. The Bot runs uc-storefront auth login --profile main and 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.

  5. Confirm.

    • auth status shows credential store: encrypted-file (durable, available), local grant: present and credential key: set, and shows the same in a new session.
    • uc-storefront sf storefronts lists 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. init and skills install take --no-input. Without a saved or named target, a non-interactive init refuses with targets_required.
  • Errors. A JSON error has the shape { "formatVersion": 1, "error": { "code": "...", "message": "...", "paths": [] } }. Branch on error.code, never on the message text. A refusal from UltraCart's server adds error.server with its own status and code.
  • Exit codes. 0 is success. 1 is an operational failure. 2 is invalid arguments, configuration, a conflict or a refused downgrade. 3 means skills status --check found drift, or a command is waiting on an approval or secret request.
  • Skill drift in CI. uc-storefront skills status --check exits 3 when 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.

Was this page helpful?