External Writes — Admin Guide
External Writes let Max post content back to connected systems on behalf of users — for example, creating a draft task in a Replit workspace that corresponds to an Align entry. Every write requires explicit user confirmation before anything happens.
External Writes are disabled by default at both the platform and organisation levels. Both a platform admin and an org admin must take action before any user can trigger them.
Supported actions (current)
| System | What Max can write | Capability name |
|---|---|---|
| Replit | Draft task in a workspace, linked to an Align entry | task.create_draft |
| GitHub | Comment on an issue or pull request | task.link |
Slice 1 note — Replit: The current release writes an
external_task_mappingsrecord in Align and returns a structured handoff prompt. A live call to the Replit MCP API is not made until Slice 2 (whenliveWriteEnabledis flipped on the server). Admins can enable the capability now to trial the confirmation flow safely.
Requirements
External Writes require three conditions to be met simultaneously:
1. Server-side enable (deployment team / platform admin)
The server must have the following environment variable set:
ASSISTANT_EXTERNAL_WRITES_ENABLED=true
This is a global kill switch. When it is absent or false, no live-write external action can execute regardless of org settings. Set it in your deployment environment (Railway secret, Doppler, or .env for local development).
Additional optional env vars:
| Variable | Purpose | Default |
|---|---|---|
ASSISTANT_EXTERNAL_WRITES_PILOT_ORGS | Comma-separated org IDs allowed to use live writes. Empty = all orgs. | (open) |
ASSISTANT_EXTERNAL_WRITES_SANDBOX_REPOS | GitHub only — comma-separated owner/repo values allowed as write targets. | (none) |
ASSISTANT_EXTERNAL_WRITES_SANDBOX_ONLY | GitHub only — when true, writes blocked unless repo is in sandbox list. | true |
Replit slice 1: Because
liveWriteEnabledisfalsefortask.create_draft,ASSISTANT_EXTERNAL_WRITES_ENABLEDdoes not gate Replit handoffs in the current release. The org-level feature flags (step 2) are the only gate.
2. Per-organisation feature flags (platform admin)
A platform admin must enable both flags for the organisation via Platform Admin → Tenants → [tenant] → Feature Flags:
| Flag label | Internal name | Must be on |
|---|---|---|
| MCP Server | featureMcpV1 | Yes — prerequisite for all MCP-based tools |
| Max External Writes | featureAssistantExternalWritesV1 | Yes — gates mcp.external_action.propose |
See the Platform Admin Guide for step-by-step instructions.
3. Project-level Replit workspace ID (org admin)
For the Replit task.create_draft capability, each project that should support handoffs must have a Replit Workspace ID configured:
- Go to Projects → [project] → Settings (gear icon, or via the admin project list).
- Scroll to the Replit section under the Integrations tab.
- Enter the workspace ID in the Replit Workspace field and save.
If this field is blank, Max will tell the user: "This project doesn't have a Replit workspace configured — ask an admin to add one in project settings." No proposal is made.
User confirmation flow
When all conditions are met and a user asks Max to send work to an external system:
- Max proposes — a confirmation card appears in the Max panel showing exactly what will be written: the target system, entry title, and a preview of the content.
- User reviews — the user reads the preview and can cancel at any step.
- User confirms — Max executes the write and reports the outcome.
Nothing is sent to any external system until the user explicitly clicks Confirm.
Role requirements
External Write proposals are only available to users with the following roles:
| Role | Can trigger External Writes |
|---|---|
| Platform Admin | Yes |
| Admin | Yes |
| Manager | Yes |
| Tech Lead | Yes |
| Developer | Yes |
| Tester | Yes |
| Client | No |
| Viewer | No |
Disabling External Writes
- Per-org: A platform admin can toggle Max External Writes off in the tenant feature flags. Pending confirmation requests will fail with a clear error message.
- Globally: Set
ASSISTANT_EXTERNAL_WRITES_ENABLED=false(or remove it) and restart the server. No new live writes will execute.
Audit log
Every External Write attempt — successful, cancelled, or failed — is recorded with:
- Acting user and role
- Target system and capability name
- Entry and project context
- Outcome and error code (if any)
- Timestamp
Accessible via Settings → Activity Log (admins) or the platform audit trail (platform admins).