Skip to main content

​
Deployment

This repository has been migrated to a monorepo structure using pnpm and uv workspaces, following the Nexel Dev Template best practices.

​
Architecture Overview

  • Apps (/apps):
    • platform: FastAPI backend (Private).
    • console-sentinel: Next.js management console (Private).
    • web: Next.js public website (Private).
  • Packages (/packages):
    • agent-sentinel-sdk: The core Python SDK (Mirrored to Public repo).
    • agent-sentinel-gym: Security testing environment (Private).

​
Deployment Instructions

​
1. Railway (Backend Platform)

  • Service: platform
  • Root Directory: apps/platform
  • Build Context: / (Must be the repository root to allow uv to see workspace configs).
  • Dockerfile Path: apps/platform/Dockerfile
  • Start Command: Handled by Dockerfile (bash scripts/start.sh).
  • Watch Paths (railway.json build.watchPatterns): apps/platform/**, packages/agent-sentinel-sdk/**, pyproject.toml, uv.lock, Dockerfile, railway.json, apps/platform/scripts/**. A deploy triggers on any change to these paths, including the Dockerfile and Railway config itself.
  • Migrations: run exactly once per deploy, by deploy.predeploy (bash apps/platform/scripts/prestart.sh), which runs alembic upgrade head (single head — enforced by the migrations job in .github/workflows/test.yml). scripts/start.sh does not run prestart.sh again.
  • WEB_CONCURRENCY: must stay 1 while the escalation loop runs in-process (no leader election yet); it defaults to 1 in scripts/start.sh but should also be set explicitly on the Railway service.

​
2. Vercel (Console & Web)

For both apps/console-sentinel and apps/web:
  • Root Directory: Set to apps/console-sentinel or apps/web.
  • Build Command: cd ../.. && npx turbo build --filter=<package-name>...
  • Install Command: pnpm install (Managed at root).

​
SDK Public Sync

To minimize GitHub Action costs and maintain a clean public history, the SDK is only synced to the public repository when a release tag is pushed.
  1. Iterate: Commit and push to the private monorepo main branch as usual.
  2. Release: When ready to update the public SDK:
  3. Action: The Release SDK to Public Repo workflow will trigger, extract packages/agent-sentinel-sdk, and push it to the public agent-sentinel/agent-sentinel-sdk repository.
Requirement: Ensure a GitHub Secret named SDK_SYNC_TOKEN (Fine-grained PAT with Write access to the SDK repo) is configured in the monorepo settings.

​
Local Development

  • Install All: just install (or uv sync && pnpm install)
  • Run Dev: npx turbo dev
  • Test All: npx turbo test
  • Lint All: npx turbo lint