App Web IDE

Enable a code-server Web IDE in your app’s browser, eliminating the need for a local dev environment to edit, commit, and redeploy.

Today (M1): the IDE toggle persists your intent and returns the would-be URL with status=“running”, but code-server is not installed and the gateway route is not registered yet. M1.5 will swap in real guest-agent provisioning. All response shapes (MCP and REST) are stable; you can wire your automation and UI now.

How it works

1. Enable — call enable_app_ide(app_id) to flip the IDE binding on for an app and get the URL https://ide-<slug>.apps.openfactory.tech.
2. Open — browse to that URL. The editor opens at the app’s checkout directory /opt/services/<repo>/ once real provisioning is live in M1.5.
3. Check status — call get_app_ide_status(app_id) to see the current binding (enabled, url, status, timestamps).
4. Disable — call disable_app_ide(app_id) to stop code-server and tear down the gateway route when done.

Both enable and disable are idempotent: enabling an already-running IDE is a no-op, and so is disabling one that is off.

MCP tools

All MCP responses include a session_token field with the user ID. The enable_app_ide tool also includes a next field with contextual guidance.

enable_app_ide

Provision and start the code-server Web IDE for an app at https://ide-<slug>.apps.openfactory.tech.

Example call:

enable_app_ide(app_id='550e8400-e29b-41d4-a716-446655440000')

MCP response (includes session_token and next):

{
  "enabled": true,
  "url": "https://ide-myapp.apps.openfactory.tech",
  "port": 8443,
  "status": "running",
  "enabled_at": "2026-06-26T15:30:00Z",
  "disabled_at": null,
  "notes": "STUB MODE — no real code-server install or gateway route.",
  "session_token": "user@example.com",
  "next": "Open https://ide-myapp.apps.openfactory.tech (owner-only, auth-gated). Edit, commit via the IDE's git UI, then deploy_app(...) to ship the change. The integrated terminal is a shell inside the app's VM."
}

get_app_ide_status

Retrieve the current IDE binding state (enabled, url, status, timestamps). Returns a default off-binding if never enabled.

Example call:

get_app_ide_status(app_id='550e8400-e29b-41d4-a716-446655440000')

MCP response (includes session_token):

{
  "enabled": true,
  "url": "https://ide-myapp.apps.openfactory.tech",
  "port": 8443,
  "status": "running",
  "enabled_at": "2026-06-26T15:30:00Z",
  "disabled_at": null,
  "notes": null,
  "session_token": "user@example.com"
}

disable_app_ide

Stop code-server and remove the IDE gateway route for an app.

Example call:

disable_app_ide(app_id='550e8400-e29b-41d4-a716-446655440000')

MCP response (includes session_token):

{
  "enabled": false,
  "url": null,
  "port": 8443,
  "status": "off",
  "enabled_at": "2026-06-26T15:30:00Z",
  "disabled_at": "2026-06-26T16:00:00Z",
  "notes": "STUB MODE — no real teardown.",
  "session_token": "user@example.com"
}

REST API

The same operations are available over HTTP. All routes are owner-scoped: they require a session cookie or X-Guest-Id header, return 401 if unauthenticated, and 404 if the app is not owned by the caller.

REST responses return the IdeBinding model directly (no session_token or next fields, unlike MCP responses).

REST response shape

{
  "enabled": true,
  "url": "https://ide-myapp.apps.openfactory.tech",
  "port": 8443,
  "status": "running",
  "enabled_at": "2026-06-26T15:30:00Z",
  "disabled_at": null,
  "notes": null
}

End-to-end example

1. Create or open an existing app and note its app_id.
2. Call enable_app_ide(app_id) via MCP or POST /api/apps/{app_id}/ide. The response carries the URL https://ide-<slug>.apps.openfactory.tech with status="running".
3. Navigate to that URL in the browser. The IDE loads at the app’s checkout directory /opt/services/<repo>/ once real provisioning lands in M1.5.
4. Edit files in the browser editor, use the integrated terminal for shell commands inside the app VM, and commit changes via the IDE’s Git UI.
5. Call deploy_app(app_id, vm_name=...) or trigger a redeploy from the IDE surface to ship the committed changes to production.
6. Call disable_app_ide(app_id) to stop the service and remove the route when done.

Key details

• Stable URL: The IDE URL always follows the app’s slug: https://ide-<slug>.apps.openfactory.tech. Bookmark it.
• Owner-scoped: Only the app’s owner can enable, disable, or read the binding. Non-owners receive 404 from the gateway.
• Idempotent: Re-enabling an enabled IDE or disabling a disabled one is a no-op and returns the current binding.
• Stub mode: M1 records the binding and returns the URL, but code-server is not installed and the gateway route is not registered. M1.5 swaps in real guest-agent provisioning behind the same API.
• MCP vs. REST: MCP responses include session_token (all tools) and next (enable_app_ide only) fields. REST responses return the IdeBinding object directly without these extra fields.

Related

• App Deployment — deploy your app to production, pair with the IDE to edit and redeploy from the browser.