Skip to main content

Local dev stack

The dev stack is the recommended way to run Shellui locally. One command starts every backend, every front-end, Postgres, Redis and Mailpit. Your code is mounted from disk, so Django reloads and Vite hot reloads on save.

Requirements​

  • Docker with Compose v2
  • uv or Python 3 (to generate .env.local)
  • OpenSSL

1. Clone the repos side by side​

mkdir shellui && cd shellui
for repo in shellui identity-service storage-service hosting-service email-service saas-service ai-service admin dashboard files playground; do
git clone -b develop git@github.com:shellui/$repo.git
done

You should end up with:

shellui/
shellui/
identity-service/
storage-service/
hosting-service/
email-service/
saas-service/
ai-service/
admin/
dashboard/
files/
playground/

saas-service and dashboard are private. Clone them with access to the Shellui org.

2. Start​

cd shellui/dev
./start.sh

On first run, start.sh creates dev/.env.local with fresh secrets. Later runs keep it and only append variables added to the example since (generate-env.sh, which uses uv run when available, else python3). It then runs docker compose --env-file .env.local up --build with the full stack, email-worker included. Extra arguments go to Compose, for example ./start.sh -d.

On every ./start.sh, the stack creates any missing Postgres database after Postgres is healthy and before the backends that use Postgres start. The databases are identity, identity_global, storage, hosting, email, saas, ai, and ai_global. The next ./start.sh creates ai_global when the volume predates that database.

Never commit dev/.env.local.

3. Open​

ServiceURL
shellhttp://localhost:4000
identityhttp://localhost:8001
identity-globalhttp://localhost:8007
storagehttp://localhost:8002
hostinghttp://localhost:8003
emailhttp://localhost:8004
saashttp://localhost:8005
aihttp://localhost:8006
ai-globalhttp://localhost:8008
adminhttp://localhost:5173
dashboardhttp://localhost:5174
fileshttp://localhost:5175
playgroundhttp://localhost:5176
Mailpit UIhttp://localhost:8025
Mailpit SMTPlocalhost:1025
Postgreslocalhost:5432
Redislocalhost:6379

Browser URLs and token issuers use http://${DEV_PUBLIC_HOST}:<port>. The example sets DEV_PUBLIC_HOST to a Tailscale address. Set it to localhost when the browser is on the same machine. The table lists the ports. identity-global is port 8007. ai-global is port 8008. In the steps below, use that host in place of localhost when it is not localhost. Calls between containers use http://<service>:8000, for example http://identity:8000/.well-known/jwks.json, http://identity-global:8000/.well-known/jwks.json, and http://ai-global:8000/.well-known/jwks.json.

Which identity each app uses​

The stack always starts two identity-service processes. They do not share a database, a Redis DB index, a SECRET_KEY, or a JWT signing key. SHELLUI_INSTANCE_ROLE is region on identity and global on identity-global.

AppIdentityHow it is reached
shell, admin, files, playgroundregionhttp://localhost:8001
storage, hosting, email, airegionhttp://identity:8000 on the Compose network
dashboardglobalhttp://localhost:8007 (IDENTITY_SERVICE_URL)
saas, ai-globalglobalhttp://identity-global:8000 (IDENTITY_INTERNAL_URL or GLOBAL_IDENTITY_INTERNAL_URL)

REGION_CH_IDENTITY_ORIGIN stays http://localhost:8001. The dashboard uses that value for the ch region row. Sign-in for the dashboard itself uses identity-global.

Which ai-service each client uses​

The stack always starts two ai-service processes from the same image. They do not share a database, a Redis DB index, a SECRET_KEY, or a signing key. AI_SERVICE_MODE is region on ai and global on ai-global.

ClientModeHow it is reached
shell, admin, company MCPregionhttp://localhost:8006 (/c/<company_id>/mcp)
storage, hosting, email calls from the region gatewayregionhttp://storage:8000, http://hosting:8000, http://email:8000
Shellui account MCPglobalhttp://localhost:8008 (/mcp)
saas API tokens and Region.ai_urlglobal issuer, region URLAI_GLOBAL_ISSUER is http://localhost:8008. REGION_CH_AI_URL is http://localhost:8006

The region process does not set SAAS_SERVICE_URL. SaaS tools are on ai-global. ai-global signs in through identity-global (GLOBAL_IDENTITY_URL, internal http://identity-global:8000) with GLOBAL_OIDC_CLIENT_ID. That client is the second entry in IDENTITY_GLOBAL_OIDC_CLIENTS. Its redirect is {PUBLIC_AI_GLOBAL_URL}/oauth/mcp/signin/complete. Company tools exchange at regional identity (http://identity:8000 on the Compose network, http://localhost:8001 from the host). SaaS tool calls use SAAS_SERVICE_URL (http://localhost:8005) and SAAS_SERVICE_INTERNAL_URL (http://saas:8000). The saas API token aud is SAAS_API_AUDIENCE (http://localhost:8005/api).

REGION_CH_AI_ORIGIN stays on the dashboard. saas reads REGION_CH_AI_URL for the same regional origin.

Regional identity trusts one user issuer and two agent issuers. It does not fetch JWKS over the network.

User tokens come from identity-global:

  • GLOBAL_ISSUER_URL is http://localhost:8007. The user token iss must match that origin.
  • GLOBAL_ISSUER_INTERNAL_URL is http://identity-global:8000, for code exchange inside Compose.
  • GLOBAL_JWKS is identity-global's public key.
  • GLOBAL_ACCESS_TOKEN_AUDIENCE is shellui_global, the same value as identity-global JWT_AUDIENCE.
  • GLOBAL_CLIENT_ID and GLOBAL_CLIENT_SECRET match IDENTITY_GLOBAL_OIDC_CLIENTS on identity-global.

Agent tokens for the global MCP come from ai-global. During migration, regional identity also trusts tokens saas still mints.

  • GLOBAL_AGENT_ISSUER_URL on regional identity is http://localhost:8008 (PUBLIC_AI_GLOBAL_URL).
  • GLOBAL_AGENT_JWKS is the public key of AI_GLOBAL_SERVICE_SIGNING_KEY. Inside the ai-global container that PEM is AI_SERVICE_SIGNING_KEY. It is not identity-global's JWT key and not the saas key.
  • GLOBAL_AGENT_LEGACY_ISSUER_URL is http://localhost:8005. GLOBAL_AGENT_LEGACY_JWKS is the public key of GLOBAL_AGENT_SIGNING_KEY. GLOBAL_AGENT_KEY_ID is the kid in that legacy JWKS. Drop this pair at cutover.
  • GLOBAL_AGENT_ACCESS_TOKEN_AUDIENCE is shellui_global_agent_dev. ai-global, saas, and regional identity all read that name.
  • GLOBAL_MCP_URL on regional identity is http://localhost:8008/mcp. Personal status returns that URL. When the variable is empty, identity uses {DASHBOARD_PUBLIC_URL}/mcp.

saas keeps GLOBAL_ISSUER_URL at http://localhost:8005 so tokens it still mints match the legacy issuer. It verifies ai-global saas API tokens with AI_GLOBAL_ISSUER and AI_GLOBAL_JWKS.

ai-service region ignores SAAS_SERVICE_URL and must not set GLOBAL_IDENTITY_URL, GLOBAL_OIDC_CLIENT_ID, GLOBAL_OIDC_CLIENT_SECRET, or SAAS_API_AUDIENCE. global reads GLOBAL_IDENTITY_*, GLOBAL_OIDC_*, SAAS_SERVICE_INTERNAL_URL, and SAAS_API_AUDIENCE, signs with AI_SERVICE_SIGNING_KEY, and must not set regional identity, storage, hosting, or EMAIL_SERVICE_API_KEY. identity-service accepts GLOBAL_AGENT_LEGACY_ISSUER_URL and GLOBAL_AGENT_LEGACY_JWKS next to GLOBAL_AGENT_ISSUER_URL and GLOBAL_AGENT_JWKS, and reads GLOBAL_MCP_URL for personal status. saas-service reads AI_GLOBAL_ISSUER, AI_GLOBAL_JWKS, and REGION_CH_AI_URL (Region.ai_url, token aud SAAS_API_AUDIENCE). identity-global registers whatever OIDC_CLIENTS lists, including the ai-global client.

Try the global to regional exchange​

Use a non-staff account. admin / admin is staff on both databases. Regional identity refuses staff on token exchange (RFC 8693).

  1. Open the dashboard at http://localhost:5174. Sign-in goes to identity-global at http://localhost:8007, company 1. Request a magic link for dev@localhost and open it from Mailpit at http://localhost:8025. The shell at http://localhost:4000 still signs in at http://localhost:8001.
  2. In the dashboard, create or connect a company. SaaS calls the regional provisioning API on http://localhost:8001. The regional database already has company 1 (Shellui Dev, public access) from seed_dev, which is enough for a local exchange target.
  3. Global MCP for a Shellui account is POST http://localhost:8008/mcp (ai-global). saas POST http://localhost:8005/mcp stays until cutover. After consent, exchange the global agent access token for a company MCP token. SUBJECT_TOKEN is the ai-global agent JWT (iss http://localhost:8008, aud shellui_global_agent_dev). A saas-minted token (iss http://localhost:8005, same aud) still exchanges while GLOBAL_AGENT_LEGACY_ISSUER_URL is set.
G=urn:ietf:params:oauth:grant-type:token-exchange
A=urn:ietf:params:oauth:token-type:access_token
curl -sS -X POST "http://localhost:8001/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=${G}" \
--data-urlencode "subject_token=${SUBJECT_TOKEN}" \
--data-urlencode "subject_token_type=${A}" \
--data-urlencode "requested_token_type=${A}" \
--data-urlencode "company_id=1" \
--data-urlencode "resource=http://localhost:8006/c/1/mcp" \
--data-urlencode "access_mode=read_only" \
--data-urlencode "read_level=safe" \
--data-urlencode "allow_destructive=false" \
--data-urlencode "services=identity" \
--data-urlencode "services=storage"

The response is a regional token whose aud is http://localhost:8006/c/1/mcp. Send that token to the company MCP URL. Do not send the global JWT there.

A global user access token (magic link on identity-global, aud shellui_global, token_type access) uses the same token endpoint with company_id and no resource. The regional server returns a regional session for that company.

  1. Device login stays on the regional server. The client calls POST http://localhost:8001/oauth/mcp/device/code with resource set to http://localhost:8006/c/1/mcp. Open http://localhost:8001/oauth/mcp/device, sign in with dev@localhost on the regional server (http://localhost:8001), and allow the code. Staff cannot approve.

Common commands​

Run these from shellui/dev.

./start.sh -d                                      # start in the background
docker compose --env-file .env.local logs -f identity # follow one service
docker compose --env-file .env.local down # stop everything
./start.sh -d identity # rebuild and restart one service
docker compose --env-file .env.local exec identity python manage.py createsuperuser # extra users; admin/admin is seeded
docker compose --env-file .env.local down -v # stop and delete all data volumes

Troubleshooting​

  • A build fails on a sibling repo. Pull develop in that repo. Every image needs a dev target in its Dockerfile.
  • Port already in use. Stop the local process on that port, or the other stack using it.
  • Postgres auth fails after new secrets. You removed .env.local but kept old volumes. Run docker compose --env-file .env.local down -v, then ./start.sh.
  • No hot reload on macOS. Set DEV_FILE_WATCH_POLLING=true in dev/.env.local, then restart the front-end service. Docker Desktop virtiofs usually works with inotify when polling is off.
  • High idle CPU. Defaults favor inotify and slower Django or worker polls. Raise DEV_FILE_WATCH_POLLING, lower DJANGO_STATRELOAD_SLEEP, or lower EMAIL_LANE_WORKER_POLL_SECONDS only if you need snappier reloads.
  • Compose stop shows Error while Killing. Update Docker Compose (Desktop includes it). The dev stack does not set a restart policy so docker compose down and Ctrl-C on ./start.sh can stop containers without racing the engine. Services use init: true so SIGTERM reaches runserver, Vite, and the email worker children.
  • Dependencies changed. Rebuild that service: ./start.sh -d <service>.
  • generate-env.sh fails. Check that uv or python3, and openssl, are on PATH.

Global issuer keys (dev)​

dev/generate_env.py fills three RSA keys for these issuers. identity-global's JWT key feeds GLOBAL_JWKS. GLOBAL_AGENT_SIGNING_KEY feeds GLOBAL_AGENT_JWKS and GLOBAL_AGENT_KEY_ID (the legacy saas agent signer). AI_GLOBAL_SERVICE_SIGNING_KEY feeds AI_GLOBAL_JWKS and AI_GLOBAL_SERVICE_SIGNING_KID. On every run the script rebuilds those JWKS from the PEMs and rewrites IDENTITY_GLOBAL_OIDC_CLIENTS so the regional client and the ai-global client are both registered. An existing file keeps each private key. If identity-global's PEM matches the saas PEM, the script generates a new identity-global key and leaves the saas key in place. If the ai-global PEM matches either of those, or the regional AI_SERVICE_SIGNING_KEY, the script generates a new ai-global key. It appends missing names and does not replace POSTGRES_PASSWORD.

dev/docker-compose.yml passes GLOBAL_ISSUER_URL (http://localhost:8007), GLOBAL_JWKS, GLOBAL_ACCESS_TOKEN_AUDIENCE, GLOBAL_AGENT_ISSUER_URL (http://localhost:8008), GLOBAL_AGENT_JWKS (the ai-global key), GLOBAL_AGENT_LEGACY_ISSUER_URL (http://localhost:8005), GLOBAL_AGENT_LEGACY_JWKS, and GLOBAL_AGENT_ACCESS_TOKEN_AUDIENCE into identity. saas receives GLOBAL_ISSUER_URL http://localhost:8005, plus GLOBAL_AGENT_SIGNING_KEY, GLOBAL_AGENT_KEY_ID, GLOBAL_AGENT_ACCESS_TOKEN_AUDIENCE, AI_GLOBAL_ISSUER, AI_GLOBAL_JWKS, and REGION_CH_AI_URL. See Identity MCP and agents. GLOBAL_AGENT_PRIVATE_KEY is not used in dev/.env.local.example.

Migrate an existing local stack​

From shellui/dev, refresh the env file. New names are appended. Private keys that are already set stay, except when identity-global's key is the same PEM as GLOBAL_AGENT_SIGNING_KEY: then identity-global gets a new key. The same rule gives ai-global a new key when its PEM matches another signing key. GLOBAL_JWKS, GLOBAL_AGENT_JWKS, GLOBAL_AGENT_KEY_ID, AI_GLOBAL_JWKS, AI_GLOBAL_SERVICE_SIGNING_KID, GLOBAL_AGENT_ISSUER_URL, and IDENTITY_GLOBAL_OIDC_CLIENTS are rewritten so they match those keys and the two OIDC clients.

./generate-env.sh

Running ./start.sh creates any missing Postgres database, including when the data volume predates identity_global. Leave that volume in place. To drop every database and secret, remove .env.local and run docker compose --env-file .env.local down -v, then ./start.sh.

Redis​

One Redis instance. Each backend uses its own DB: identity 0, storage 1, hosting 2, email 3, saas 4, ai 5, identity-global 6, ai-global 7. Values live in dev/.env.local.example as *_REDIS_URL.

Workers​

The Django dev containers run runserver only. email-worker runs lane delivery and the scheduler, and starts with ./start.sh by default.

Email​

Mail lands in Mailpit at http://localhost:8025. generate-env.sh writes one email-service key per caller (IDENTITY_, STORAGE_, HOSTING_, SAAS_ and AI_EMAIL_SERVICE_API_KEY). On start, email-service registers them from EMAIL_DEV_SERVICE_KEYS, storing only their hashes. Nothing to do by hand. This only runs with DEBUG=true, so production never seeds keys.

This repository in the stack​

The shell service builds the dev target from the root Dockerfile, bind-mounts the monorepo at /app, and runs the CLI dev server on port 4000 with the split config in dev/config/ (one shellui.<section>.config.json per section, like shellui config split writes).

Local @shellui/* packages (no npm publish)​

The dev stack bind-mounts this monorepo into every front-end container at /opt/shellui (read-only). Scripts in dev/container/ run on container start:

  1. link-local-shellui-packages.mjs replaces node_modules/@shellui/* with symlinks into /opt/shellui/packages/* for every @shellui dependency declared in that app (lockfiles stay on published versions; only the Compose node_modules volume is touched).
  2. run-vite-dev.mjs loads the app’s normal vite.config.* and adds Vite aliases so @shellui/sdk and @shellui/core resolve to TypeScript source for hot reload.

shell already runs from the mounted monorepo workspace (/app). admin, dashboard, files, and playground use the shared entrypoint and Vite wrapper. Production Dockerfiles and CI are unchanged.

After you change pnpm-lock.yaml in a sibling app, rebuild that service: ./start.sh -d <service>.

playground runs the playground Vite dev server on port 5176 with hot reload (PLAYGROUND_DEV_PORT). Admin owns 5173 in the stack.

files runs on port 5175 with VITE_STORAGE_URL, VITE_IDENTITY_URL, and HMR env vars set in compose. The shell config sets storage.url to http://localhost:8002 and storage.filesUrl to http://localhost:5175/ via PUBLIC_STORAGE_URL and PUBLIC_FILES_URL.

Shell service env​

The files in dev/config/ resolve ${VAR:-default} placeholders from the container environment (same names as dev/.env.local).

dev/.env.local variablePurpose
PUBLIC_IDENTITY_URLbackend.url
PUBLIC_ADMIN_URLbackend.adminUrl
PUBLIC_EMAIL_URLemail.url
PUBLIC_STORAGE_URLstorage.url
PUBLIC_FILES_URLstorage.filesUrl
PUBLIC_HOSTING_URLhosting.url
PUBLIC_AI_URLaiService.url
SHELL_IDENTITY_COMPANY_IDbackend.companyId
PUBLIC_PLAYGROUND_URLplayground navigation (PLAYGROUND_APP_URL)

Sign in​

Both identity processes seed themselves on every start (IDENTITY_DEV_SEED=true in the compose file, and only when DEBUG=true). seed_dev does not take a role flag, so each database gets the same rows. There is nothing to create by hand:

  • Company 1, named Shellui Dev, with magic link on and the dev front-ends (ports 4000, 5173 to 5176) allowed as redirects.
  • admin / admin, a superuser on each identity admin (http://localhost:8001/admin/ and http://localhost:8007/admin/) and the admin app. Local only. Staff accounts cannot use magic links, so sign in with the password. Regional token exchange refuses staff.
  • dev@localhost, a normal member of company 1 for magic link. Request a link in the shell (http://localhost:4000, regional identity) or the dashboard (http://localhost:5174, identity-global) and open it from Mailpit (http://localhost:8025).

The seed never overwrites existing rows, so a changed admin password or company settings survive restarts. To start fresh, run docker compose --env-file .env.local down -v.

Sign-in stays in the browser across tabs. shellui start and serve:dist mount /api/auth unless security.bffAuth.enabled is false. The dev shell also sets that flag in dev/config/shellui.security.config.json. The host stores the refresh token in an HttpOnly shellui_refresh cookie on /api/auth, without the Secure flag on http://localhost. The browser does not call identity for the code exchange. Inside the shell container, that exchange uses http://identity:8000 (SHELLUI_BFF_BACKEND_URL) and sends the shell Origin. A saved profile that cannot be restored is cleared, and the login page comes back.

GitHub is optional. Without credentials the stack starts normally and only the GitHub button fails. To enable it, create a GitHub OAuth app with homepage http://localhost:4000 and the callback URL identity shows in its OAuth setup, then add the client ID and secret to company 1 in the admin app (http://localhost:5173) or the identity admin. Credentials are stored per company, not in .env.local.

SaaS API CORS​

saas-service reads CORS_ALLOWED_ORIGINS from compose. The generated dev/.env.local sets SAAS_CORS_ALLOWED_ORIGINS to the shell (http://localhost:4000 and http://127.0.0.1:4000) and the global dashboard Vite app (http://localhost:5174 and http://127.0.0.1:5174). If you change PUBLIC_SHELL_URL or serve the dashboard on another origin, append that origin to SAAS_CORS_ALLOWED_ORIGINS and run docker compose --env-file .env.local up -d saas (or ./start.sh). Internal service calls use Docker network URLs (http://saas:8000); they do not rely on this list.

Service-specific notes live in each repo: identity, storage, hosting, email, saas, ai and dashboard.