Skip to content
VectorStep
Blog
Beta. VectorStep is in beta.Let us know if something breaks.

Docker and Docker Compose

This is the layout the installer creates on Linux, macOS (Docker Desktop) and Windows (Docker Desktop or WSL2). Everything is in one directory, ~/.vectorstep/, and the authored files are plain host directories mounted into the containers — so a saved file is already visible inside, with no rebuild.

Where things live

Section titled “Where things live”
~/.vectorstep/
├── .env                    # keys, tokens, ports, image tag
├── docker-compose.yaml     # managed by the installer — refreshed on re-run
├── config/
│   ├── vectorstep.yaml     # service config
│   └── gateway.yaml        # Gateway config
├── pipelines/              # VectorStep pipelines
├── steps/                  # library steps
├── agents/                 # Gateway agents (agent.yaml + soul.md per directory)
└── skills/                 # Gateway skills (a SKILL.md per directory)

Change a pipeline, step, agent or skill

Section titled “Change a pipeline, step, agent or skill”

Edit or add the file under the matching directory, then reload the service that owns it.

Pipelines and steps → reload VectorStep:

Terminal window
cd ~/.vectorstep
set -a; . ./.env; set +a
curl -X POST -H "Authorization: Bearer $VECTORSTEP_ADMIN_TOKEN" http://localhost:8000/reload
# {"status":"reloaded","pipelines_loaded":17}

Agents and skills → reload the Gateway. The Gateway doesn’t publish a port to your host by default, so make the call from inside its container:

Terminal window
cd ~/.vectorstep
docker compose exec -T gateway python -c "
import json, urllib.request as u
t = json.load(open('/data/identity/device-auth.json'))['tokens']['admin']['token']
r = u.urlopen(u.Request('http://localhost:18780/reload', method='POST',
                        headers={'Authorization': 'Bearer ' + t}))
print(r.status)"

The response lists the agents and skills it loaded. If a file is invalid, the reload is rejected with the file name and the reason, and nothing changes — fix the file and reload again.

Change a shell-step script

Section titled “Change a shell-step script”

Scripts for executor: shell steps live in ~/.vectorstep/scripts/, mounted read-only into the service at /etc/vectorstep/scripts. Each one needs its execute bit and a pinned sha256 in config/vectorstep.yaml under security.shell_steps.allowed. The list is read once at startup, so a change to a script or its pin takes effect on a restart, not a reload:

Terminal window
cd ~/.vectorstep
sha256sum scripts/classify-severity.sh           # shasum -a 256 on macOS; update the pin in config/vectorstep.yaml
docker compose restart vectorstep

See Run a shell step for the full setup.

Change config.yaml or a secret

Section titled “Change config.yaml or a secret”

config/vectorstep.yaml and config/gateway.yaml are mounted read-only into the containers. Most settings are read at startup, so restart the service that owns the file:

Terminal window
cd ~/.vectorstep
docker compose restart vectorstep      # after editing config/vectorstep.yaml
docker compose restart gateway         # after editing config/gateway.yaml

The exceptions — pricing:, replay: and security policies on the service — are picked up by the reload above, no restart needed. See what reloads and what doesn’t.

Secrets and API keys live in .env. Both services receive every variable in it, so a new ${VAR} referenced from either config file only needs a line added to .env. Changing .env (or the compose file) needs the containers recreated, not just restarted:

Terminal window
docker compose up -d

Check it worked

Section titled “Check it worked”
Terminal window
docker compose logs -f vectorstep      # look for "Reloaded"
docker compose logs -f gateway
curl -s localhost:8000/health          # "config_errors": 0 when every file loaded

Notes

Section titled “Notes”
  • Upgrades don’t touch your files. install.sh --upgrade moves the image version in .env and leaves config/, pipelines/, steps/, agents/ and skills/ exactly as they are.
  • The compose file is managed. Re-running the installer refreshes docker-compose.yaml, so put your changes in .env and the config/ files rather than editing it.
  • Prefer an API over editing files? The write API validates and reloads in one call — handy from a script or CI.
Section titled “Related”