Skip to main content
TerminalUse access control matters most when you understand tasks and filesystems together.

​
The Important Rule

Tasks have dual-parent authorization. To access a task, TerminalUse evaluates both:
  • the parent agent
  • the parent filesystem path
In practice, task visibility depends on agent access and filesystem/project access together.

​
Creating A Task

When you create a task:
  • agent access is checked with run
  • filesystem access is checked separately
For an existing filesystem:
  • read permission is enough to attach it to a task
  • update permission determines whether /workspace is writable
For project_id-based auto-created filesystems:
  • update permission on the project is required
  • the resulting /workspace mount is writable

​
Why /workspace Can Be Read-Only

If the caller can run the agent and read the filesystem but cannot update the filesystem, TerminalUse still allows the task to run, but mounts /workspace read-only. That behavior is intentional. It lets users inspect or analyze files through an agent without granting write access to the underlying filesystem.

​
Resource Hierarchy

The relevant hierarchy is: 
Organization
  └── Namespace
        ├── Project
        │     └── Filesystem
        │           └── Task
        └── Agent
              └── Task
Projects are the main permission boundary for filesystems. Filesystems inherit from their parent project.

​
API Keys, Users, And Groups

Users and API keys both operate inside this authorization model. Use groups when you want to grant the same project or agent access to multiple humans or service principals.

​
Practical Consequences

  • Agent access alone does not imply filesystem write access.
  • Filesystem read access can still allow task execution with a read-only workspace.
  • Sharing a project effectively shares its filesystems.
See Keys and Secrets for the difference between API keys, webhook keys, and runtime secrets.