Platform Admin Guide
This guide covers configuration tasks that only platform admins can perform. These settings apply across all tenants hosted on the Align instance.
Platform admin access is granted by setting a user's platformRole to platform_admin via the environment variable ADMIN_EMAIL at first boot, or by an existing platform admin promoting another user from Platform Admin → Users.
Accessing the platform admin panel
Navigate to /admin in the app. You must be signed in as a platform admin to see this section. From here you can manage tenants, users, system health, and per-tenant feature flags.
Per-tenant feature flags
Feature flags are per-organisation toggles that enable or disable specific platform capabilities. They are found at:
Platform Admin → Tenants → [tenant name] → Feature Flags
Available flags
| Flag label | Internal name | What it enables |
|---|---|---|
| Assistant (Max) | featureAssistantV1 | Max AI assistant panel for all users in the org |
| MCP Server | featureMcpV1 | OAuth-gated MCP Connect Mode; required for all MCP-based tools including External Writes |
| Max External Writes | featureAssistantExternalWritesV1 | Allows Max to propose and execute writes to external systems (Replit, GitHub). Requires MCP Server to also be on. |
| Public API | featurePublicApiV1 | Enables the v1 public REST API and API key management for the org |
| Time Tracking | featureTimeTracking | Time entry logging, approval workflows, and reporting |
Enabling Max External Writes (Replit handoff)
The Replit handoff feature requires both of the following flags to be on, in this order:
- Enable MCP Server (
featureMcpV1) first. - Enable Max External Writes (
featureAssistantExternalWritesV1).
Steps:
- Go to Platform Admin → Tenants.
- Click the tenant you want to configure.
- Scroll to the Feature Flags section.
- Toggle MCP Server on and save.
- Toggle Max External Writes on and save.
The change takes effect immediately — no restart required.
What happens if only one is on:
| State | Result |
|---|---|
| Both off | Max has no MCP tools; External Writes unavailable |
| MCP Server on, Max External Writes off | MCP tools available; confirm endpoint returns 403 for external write attempts |
| MCP Server off, Max External Writes on | External Writes unavailable (MCP tools not loaded) |
| Both on | Full External Writes flow available to eligible users |
Disabling for a tenant
Toggle the flag off. Any pending confirmation requests for that org will fail with a feature_not_enabled error surfaced to the user. No data is lost.
Project-level Replit configuration (org admin responsibility)
Platform admins do not configure the Replit Workspace ID — that is done by org admins per project. However, platform admins should communicate this requirement to org admins when enabling Max External Writes.
Org admins set it at: Projects → [project] → Settings → Integrations → Replit → Replit Workspace field.
Without a Workspace ID on the project, Max will propose a handoff but show the user an error asking them to contact their admin.
Server environment variables for External Writes
These are set in the deployment environment (Railway via Doppler, .env locally). See docs/ops/doppler-setup.md for the full secret inventory.
| Variable | Required for | Effect when absent |
|---|---|---|
ASSISTANT_EXTERNAL_WRITES_ENABLED | Live-write capabilities (e.g. GitHub comments) | Live writes globally blocked; Replit slice 1 (mock) unaffected |
ASSISTANT_EXTERNAL_WRITES_PILOT_ORGS | Scoping live writes to specific orgs | All orgs are eligible (open pilot) |
ASSISTANT_EXTERNAL_WRITES_SANDBOX_REPOS | GitHub only — allowlisting target repos | All repos blocked when SANDBOX_ONLY=true |
ASSISTANT_EXTERNAL_WRITES_SANDBOX_ONLY | GitHub only — enforcing sandbox list | Defaults to true (sandbox enforced) |
Replit slice 1:
task.create_drafthasliveWriteEnabled: falsein this release, soASSISTANT_EXTERNAL_WRITES_ENABLEDdoes not gate it. Only the two org-level feature flags and the project Workspace ID matter.
Audit and observability
All external write attempts — proposals, confirmations, failures, and cancellations — are logged in the platform audit trail. For each event you will see:
- Tenant / org ID
- Acting user and role
- Capability name (
task.create_draft,task.link, etc.) - Entry and project context
- Outcome (
succeeded,failed,denied,dry_run_ok, etc.) - Error code if applicable
Access via Platform Admin → Audit Events or query platform_audit_events directly in the database.
FAQ
Q: A user says Max always returns "External write actions are not enabled for your organisation" — what do I check?
Check that both featureMcpV1 and featureAssistantExternalWritesV1 are on for that user's org in Platform Admin → Tenants.
Q: A user says Max tells them "This project doesn't have a Replit workspace configured" — what do I do?
This is an org admin task. Ask the project owner or org admin to go to Project Settings → Integrations → Replit and enter the Workspace ID.
Q: Can I enable External Writes for all tenants at once?
No — flags are per-tenant by design. Use the API (PATCH /api/admin/orgs/:id/feature-flags) with a platform admin API key if you need to script bulk enablement.
Q: What roles can trigger a Replit handoff?
Admin, Manager, Tech Lead, Developer, and Tester. Client and Viewer roles cannot.
Q: Does the confirm endpoint validate the org flag on every request?
Yes. The flag is checked at confirm time, not just at proposal time. If an admin turns the flag off between a proposal and a confirmation, the confirmation will return 403.