Docker (recommended):
cp .env.example .env # set POSTGRES_PASSWORD; optionally an LLM key
docker compose up -d --build
docker compose logs artex | grep "Setup token"Open http://localhost:8787. The first visit to /setup asks for the one-time setup
token printed at startup ([auth] no admin password is set. Setup token for the /setup page: ... in server/auth.go).
From source (no embedded UI):
go run ./cmd/artex # backend only, 127.0.0.1:8787
cd web && npm run dev # UI on :5173, /api proxied to the backend
# or: ./dev.sh # both, plus the traffic proxy on :8788The process prints one [config] snapshot {...} line at startup. It is the authoritative
record of the effective configuration: config path, DSN source and redacted DSN,
data/skill/key directories, listen address, proxy, noise profile, untrusted-output
boundary and trusted proxies. No password or token value is ever logged there.
| Setting | Resolution order | Code |
|---|---|---|
| Config file | ARTEX_CONFIG → ./config.json → config.json next to the binary |
config.Path |
| PostgreSQL DSN | ARTEX_PG_DSN → database.dsn → assembled host/port/user/password/dbname |
config.PostgresDSN |
| Skill directory | ARTEX_SKILL_DIR → skill_dir → <binary dir>/skills |
config.SkillDir |
| JWT / secret key directory | ARTEX_JWT_KEY_DIR → <binary dir> (never the browsable data dir) |
config.KeyDir |
| Secret encryption key | ARTEX_SECRET_KEY → <key dir>/secret.key → newly generated key file |
db.InitSecrets |
| Noise profile | ARTEX_NOISE_PROFILE (off default; quiet, balanced, aggressive), also settable in UI |
egress.ProfileFromEnv |
| Untrusted-output boundary | on by default; ARTEX_UNTRUSTED_BOUNDARY=0|false|off|no disables it |
agent/untrusted_boundary.go |
| Trusted proxies for login rate limit | ARTEX_TRUSTED_PROXIES (comma-separated IPs/CIDRs; empty trusts none) |
server.ParseTrustedProxies |
| Target user agent | ARTEX_TARGET_USER_AGENT (applied by non-off noise profiles) |
egress.ProfileByName |
| Budgets | ARTEX_TASK_BUDGET_TOKENS / _TURNS, ARTEX_INTENT_BUDGET_TOKENS / _TURNS |
agent/budget.go |
| Live model judge test | ARTEX_REVIEW_LIVE_CONFIG (opt-in integration test only) |
server/intercept_live_test.go |
Agent profiles, providers, notifications and other runtime settings live in the database
and are edited in System → LLM / Settings / Notify, not in config.json.
scripts/backup.sh # database dump only, 14 rotations
scripts/backup.sh --with-data --keep 30 # also archive the data/ bind mountThe dump runs inside the postgres compose service, so no host psql is needed. Restore:
gunzip -c backups/artex-db-<ts>.sql.gz | docker compose exec -T postgres \
psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"Back up the key directory as well: without it, JWTs cannot be verified and sealed secrets cannot be decrypted. Keep it outside the database backup but under the same access controls.
jwt.key— signing key for the 7-day HS256 session tokens. Replacing it invalidates every existing session; all users must log in again. Existing key files are never overwritten by startup (loadOrCreateJWTKey).secret.key(orARTEX_SECRET_KEY) — AES-256-GCM key for API keys, MCP env, task credentials and captured auth headers. Startup never overwrites an existing key. If it changes, values sealed under the old key cannot be decrypted (the code returns an error rather than leaking ciphertext as plaintext). Re-enter those secrets in the UI, or keep the previous key available until the migration is complete.
Plan a short maintenance window for either rotation.
GET /api/health— liveness, build version and provider health.GET /api/logs,GET /api/logs/stream— live backend log sink; the UI shows it under System → Logs. The startup snapshot line is here too.scripts/verify.sh— reproduces the CI checks locally (gofmt, build, vet, tests, web type-check and unit tests, shellcheck, python checks).--fulladds-raceand the web static build;--go-only/--web-onlynarrow the run../scripts/backup.sh --help— backup options.
When Postgres is not configured, database-dependent tests skip themselves; that is
expected. Set ARTEX_PG_DSN to run them. CI uses go test -p 1 ./... because test
packages share a Postgres service and use suffixed per-package databases
(SuffixTestDatabase).