Table of contents

Configuration

The CLI is configured by a few files and a handful of environment variables. Environment variables always win over files.

Files

PathHolds
~/.config/podstack/credentials.jsonYour API key (written by podstack auth login, mode 0600)
~/.podstack/config.jsonGlobal settings — notably your default project_id
./.podstack/config.jsonPer-project settings, including the sandbox block used for previews

Example ~/.podstack/config.json:

{
  "project_id": "b90d34a5-…"
}

Example per-project ./.podstack/config.json (the coding agent writes the sandbox block itself):

{
  "sandbox": {
    "image": "python-3.12",
    "port": 8000,
    "setup": "pip install -r requirements.txt",
    "run": "uvicorn main:app --host 0.0.0.0 --port 8000"
  }
}

Environment variables

VariableEffect
PODSTACK_API_KEYUse this psk_ key instead of the stored credentials (CI-friendly)
PODSTACK_PROJECT_IDOverride the default project for a single run

Output format

Every command accepts --output json or --output table. The default is a human table on a terminal and JSON when the output is piped, so scripting just works:

podstack gpu instances list --output json | jq '.[].id'

Agent project files

Inside a project the coding agent also uses:

  • .podstack/PODSTACK.md — instructions the agent always follows (create with /init).
  • .podstack/plans/ — implementation plans.
  • .podstack/progress.json — the resumable build checkpoint.

You’ll usually want to commit PODSTACK.md and plans/ but git-ignore progress.json.