Modal Workspace Administration

Use this skill when managing workspaces, environments, team access, service users, billing, or proxy tokens on Modal (SDK 1.5.x).

When to Use This Skill

• Setting up workspace environments (dev/staging/prod)
• Configuring role-based access control (RBAC)
• Creating service users for CI/CD
• Managing workspace membership and roles
• Generating billing reports (workspace or environment scoped)
• Managing proxy tokens for Servers/Endpoints auth
• Setting up SSO (Okta, SAML)
• Managing deployments and rollbacks

Workspaces

A workspace groups all Modal resources (Apps, Functions, Volumes, Secrets, etc.) for a team. Each workspace has an isolated namespace.

Workspace roles

In the SDK, Workspace.members.list() reports the lowest-privilege role as "member" (not "user").

modal.Workspace (SDK)

from datetime import datetime, timezone
import modal

ws = modal.Workspace.from_context()

# Members
for m in ws.members.list():
    print(m.name, m.role)  # role is "owner" | "manager" | "member"

# Settings (Owner/Manager)
print(ws.settings.list())
ws.settings.set("default-environment", "dev")
# Also: image-builder-version

# Proxy tokens (Servers/Endpoints auth headers Modal-Key / Modal-Secret)
token = ws.proxy_tokens.create()  # save token_id / token_secret once
ws.proxy_tokens.allow(token.token_id, "production")  # RBAC: scope to env
ws.proxy_tokens.list(environment_name="production")
ws.proxy_tokens.revoke(token.token_id, "production")
ws.proxy_tokens.delete(token.token_id)

# Billing report (replaces modal.billing.workspace_billing_report)
rows = ws.billing.report(
    start=datetime(2026, 6, 1, tzinfo=timezone.utc),
    resolution="d",
    tag_names=["*"],
)

Workspace CLI

modal workspace members list
modal workspace settings list
modal workspace settings set default-environment dev
modal workspace proxy-tokens create
modal workspace proxy-tokens list
modal workspace proxy-tokens allow wk-... production
modal workspace proxy-tokens revoke wk-... production
modal workspace proxy-tokens delete wk-...
modal billing report --for "last month" --show-resources

Environments

Environments isolate Modal resources within a workspace (e.g., dev, staging, production). Treat them as security boundaries when RBAC is enabled.

modal environment create staging
modal environment list
modal deploy --env staging my_app.py
export MODAL_ENVIRONMENT=staging

modal.Environment (SDK)

import modal

# CRUD
modal.Environment.objects.create("staging")
modal.Environment.objects.create("production", restricted=True)
envs = modal.Environment.objects.list()
env = modal.Environment.from_name("production")
# modal.Environment.objects.delete("staging")  # irreversible

# RBAC roles on restricted environments
print(env.roles.list())
# {"users": {"alice": "contributor", ...}, "service_users": {"ci-bot": "viewer", ...}}
env.roles.update(
    users={"alice": "contributor", "bob": "viewer"},
    service_users={"ci-bot": "contributor"},
)

# Environment-scoped billing
from datetime import datetime, timezone
env.billing.report(start=datetime(2026, 6, 1, tzinfo=timezone.utc))

Roles are contributor, viewer, or no-access. Workspace members can be assigned roles only on restricted environments; service users can be assigned on any environment.

Restricted environments (RBAC)

RBAC is available on Team and Enterprise plans.

modal environment create --restricted production

When an environment is restricted:

• All Members get Viewer access (read-only)
• Owners/Managers get Contributor access automatically
• Specific users/service users can be granted Contributor (or no-access)

modal environment roles list production
modal environment roles update production alice --role contributor
modal environment roles update production ci-bot --role contributor --service-user
modal environment billing report production --for "last month"

Service Users

Programmatic accounts for CI/CD and automated workflows.

Create

1. Workspace settings → Tokens → New Service User
2. Name must be lowercase alphanumeric (hyphens/underscores allowed)
3. Save the MODAL_TOKEN_ID and MODAL_TOKEN_SECRET — shown only once

Use in CI/CD

export MODAL_TOKEN_ID=your-token-id
export MODAL_TOKEN_SECRET=your-token-secret
modal deploy your_app.py

Security best practices

• Store tokens in CI/CD platform's secrets manager
• Assign service users Contributor role only on needed environments
• Use RBAC-restricted environments to isolate production from development

Continuous Deployment

GitHub Actions

name: CI/CD
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
      MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v5
        with:
          python-version: "3.10"
      - run: pip install modal
      - run: modal deploy -m my_package.my_file

For multiple environments: set MODAL_ENVIRONMENT=xyz in the workflow.

Deployment Management

Creating deployments

modal deploy -m my_package.my_file

Key behaviors

• Redeploying an existing App increments its version
• Zero-downtime deployments: traffic gradually transitions to new version
• Old containers finish processing current requests before stopping
• Image build errors abort deployment with no change to running App

Rollbacks

# Via CLI or dashboard — rollback to a previous version
# Available on Team and Enterprise plans

Rollbacks increment the version number but reset App state to a previous version.

Stopping

modal app stop <app-name>

Stopping is destructive — stopped Apps must be redeployed from source.

Go/TypeScript SDK Note

Workspace administration (RBAC, environments, service users, SSO) is managed via the Modal dashboard, CLI, and Python modal.Workspace / modal.Environment APIs.

Go/TS SDKs authenticate using the same tokens (MODAL_TOKEN_ID / MODAL_TOKEN_SECRET):

// Go — uses ~/.modal.toml or env vars automatically
mc, _ := modal.NewClient()

// TypeScript — uses ~/.modal.toml or env vars automatically
const modal = new ModalClient();

Both SDKs can target specific environments:

mc, _ := modal.NewClientWithOptions(&modal.ClientParams{
    Environment: "staging",
})

const modal = new ModalClient({ environment: "staging" });

For CI/CD, you can use Go or TypeScript SDKs alongside modal deploy (Python) — e.g., a Go service that orchestrates Sandboxes while Python defines the Functions.

Billing

Modal charges per second of resource usage:

• CPU cores
• Memory (MiB)
• GPU (per GPU-second by type)
• Disk (increases memory billing at 20:1 ratio)

You are billed for whichever is higher: your request or actual usage.

Programmatic reports (1.5.x)

Prefer object methods over the legacy module function:

These replace modal.billing.workspace_billing_report. Reports include a resource-level cost breakdown (CPU, memory, GPU types).

References

• rbac-reference.md — RBAC setup, environment roles, CLI
• service-users-reference.md — Service user management

Guardrails

• Service user tokens are long-lived — store securely, never in source code
• Use restricted environments to protect production
• Stopping an app is destructive and cannot be undone
• Always test deployments in a staging environment first
• Rollbacks and RBAC require Team or Enterprise plan
• Proxy token secrets (ws-...) are shown once — store like API tokens
• Environment.objects.delete transitively deletes all objects in that environment