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
uvor 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
| Service | URL |
|---|---|
| shell | http://localhost:4000 |
| identity | http://localhost:8001 |
| identity-global | http://localhost:8007 |
| storage | http://localhost:8002 |
| hosting | http://localhost:8003 |
| http://localhost:8004 | |
| saas | http://localhost:8005 |
| ai | http://localhost:8006 |
| ai-global | http://localhost:8008 |
| admin | http://localhost:5173 |
| dashboard | http://localhost:5174 |
| files | http://localhost:5175 |
| playground | http://localhost:5176 |
| Mailpit UI | http://localhost:8025 |
| Mailpit SMTP | localhost:1025 |
| Postgres | localhost:5432 |
| Redis | localhost: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.
| App | Identity | How it is reached |
|---|---|---|
| shell, admin, files, playground | region | http://localhost:8001 |
| storage, hosting, email, ai | region | http://identity:8000 on the Compose network |
| dashboard | global | http://localhost:8007 (IDENTITY_SERVICE_URL) |
| saas, ai-global | global | http://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.
| Client | Mode | How it is reached |
|---|---|---|
| shell, admin, company MCP | region | http://localhost:8006 (/c/<company_id>/mcp) |
| storage, hosting, email calls from the region gateway | region | http://storage:8000, http://hosting:8000, http://email:8000 |
| Shellui account MCP | global | http://localhost:8008 (/mcp) |
saas API tokens and Region.ai_url | global issuer, region URL | AI_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_URLis http://localhost:8007. The user tokenissmust match that origin.GLOBAL_ISSUER_INTERNAL_URLishttp://identity-global:8000, for code exchange inside Compose.GLOBAL_JWKSis identity-global's public key.GLOBAL_ACCESS_TOKEN_AUDIENCEisshellui_global, the same value as identity-globalJWT_AUDIENCE.GLOBAL_CLIENT_IDandGLOBAL_CLIENT_SECRETmatchIDENTITY_GLOBAL_OIDC_CLIENTSon 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_URLon regional identity is http://localhost:8008 (PUBLIC_AI_GLOBAL_URL).GLOBAL_AGENT_JWKSis the public key ofAI_GLOBAL_SERVICE_SIGNING_KEY. Inside the ai-global container that PEM isAI_SERVICE_SIGNING_KEY. It is not identity-global's JWT key and not the saas key.GLOBAL_AGENT_LEGACY_ISSUER_URLis http://localhost:8005.GLOBAL_AGENT_LEGACY_JWKSis the public key ofGLOBAL_AGENT_SIGNING_KEY.GLOBAL_AGENT_KEY_IDis thekidin that legacy JWKS. Drop this pair at cutover.GLOBAL_AGENT_ACCESS_TOKEN_AUDIENCEisshellui_global_agent_dev. ai-global, saas, and regional identity all read that name.GLOBAL_MCP_URLon 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).
- 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@localhostand open it from Mailpit at http://localhost:8025. The shell at http://localhost:4000 still signs in at http://localhost:8001. - 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. - Global MCP for a Shellui account is
POST http://localhost:8008/mcp(ai-global). saasPOST http://localhost:8005/mcpstays until cutover. After consent, exchange the global agent access token for a company MCP token.SUBJECT_TOKENis the ai-global agent JWT (isshttp://localhost:8008,audshellui_global_agent_dev). A saas-minted token (isshttp://localhost:8005, sameaud) still exchanges whileGLOBAL_AGENT_LEGACY_ISSUER_URLis 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.
- Device login stays on the regional server. The client calls
POST http://localhost:8001/oauth/mcp/device/codewithresourceset tohttp://localhost:8006/c/1/mcp. Open http://localhost:8001/oauth/mcp/device, sign in withdev@localhoston 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
developin that repo. Every image needs adevtarget 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.localbut kept old volumes. Rundocker compose --env-file .env.local down -v, then./start.sh. - No hot reload on macOS. Set
DEV_FILE_WATCH_POLLING=trueindev/.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, lowerDJANGO_STATRELOAD_SLEEP, or lowerEMAIL_LANE_WORKER_POLL_SECONDSonly 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 sodocker compose downand Ctrl-C on./start.shcan stop containers without racing the engine. Services useinit: trueso SIGTERM reaches runserver, Vite, and the email worker children. - Dependencies changed. Rebuild that service:
./start.sh -d <service>. generate-env.shfails. Check thatuvorpython3, andopenssl, are onPATH.
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:
link-local-shellui-packages.mjsreplacesnode_modules/@shellui/*with symlinks into/opt/shellui/packages/*for every@shelluidependency declared in that app (lockfiles stay on published versions; only the Composenode_modulesvolume is touched).run-vite-dev.mjsloads the app’s normalvite.config.*and adds Vite aliases so@shellui/sdkand@shellui/coreresolve 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 variable | Purpose |
|---|---|
PUBLIC_IDENTITY_URL | backend.url |
PUBLIC_ADMIN_URL | backend.adminUrl |
PUBLIC_EMAIL_URL | email.url |
PUBLIC_STORAGE_URL | storage.url |
PUBLIC_FILES_URL | storage.filesUrl |
PUBLIC_HOSTING_URL | hosting.url |
PUBLIC_AI_URL | aiService.url |
SHELL_IDENTITY_COMPANY_ID | backend.companyId |
PUBLIC_PLAYGROUND_URL | playground 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.