Skip to content
STYXDocs
Download

Docs / Reference

project.json

Every field of `.styx/project.json`, the project settings file you commit, with types, defaults and an example.

.styx/project.json holds the project settings everyone working on the repo should share: the default agent and model, the base branch, the targets, extra access rules, and how to run the app. You commit it. It never holds a secret.

Styx writes the file whenever you change one of these settings in the app. You can also edit it by hand: Styx reads it again when you come back to the Styx window, open the project, or start a task, a run or a landing, so there's no need to re-add the project. Settings that are about this machine stay on this machine when it does (see What is never in the file).

Example

{
  "$schema": "https://styx.dev/schema/project.v1.json",
  "version": 1,
  "name": "acme-shop",
  "targets": [
    { "name": "acme-shop", "provider": "vercel", "env": "prod", "authMethod": "cli", "policy": "ask-mfa" },
    {
      "name": "shop-db",
      "provider": "supabase",
      "env": "staging",
      "authMethod": "oauth",
      "config": { "ref": "abcd1234" }
    }
  ],
  "agents": {
    "default": "claude",
    "model": null,
    "permissionMode": "auto",
    "taskPermissionMode": "bypassPermissions",
    "autoApproveEdits": false
  },
  "policies": {
    "extra": [
      {
        "id": "preview-deploys",
        "rule": {
          "kind": "auto-approve",
          "match": { "provider": ["vercel"], "env": ["preview"] },
          "scopes": ["deploy"],
          "duration": "1h"
        },
        "ruleText": "Auto-approve Vercel preview deploys for 1 hour"
      }
    ]
  },
  "worktrees": { "baseBranch": "main", "branchPrefix": "agent/", "location": "sibling" },
  "dev": { "command": "pnpm dev", "url": "http://localhost:3000" },
  "checks": { "command": "pnpm typecheck && pnpm test" }
}

Fields

Only version and name are required. A field you leave out takes the default shown.

$schema

String. Styx writes https://styx.dev/schema/project.v1.json.

version

Must be 1. A file with a higher version is refused with project.json version N is newer than this Styx supports (1).

name

String, at least one character. The project's name.

targets

Array. Deploy and server targets the project uses. Each one shows up in Settings › Targets, unconnected until someone connects it on their own machine; the credential always stays in that machine's keychain.

FieldTypeNotes
namestring1–80 characters: letters, digits, space and . _ / @ : + -.
providervercel, aws, gcp, supabase, github, ssh, fly, railway, render
envprod, staging, preview, scm
authMethodoauth, key, ssh, clicli reuses the login the provider's own CLI already has.
configobjectOptional. Provider settings: Vercel projectId, teamId; AWS region, roleArn; GCP projectId, buckets; Supabase ref; GitHub owner, repo, login; SSH host, port, user; Fly.io app; Railway environmentId, service; Render serviceId.
policyask-mfa, ask, alwaysOptional. Ask · MFA, Ask each time or Always allow.

agents

Object. Defaults for new tasks (Settings › Agent defaults).

FieldTypeDefault
defaultclaude, codex, gemini, cursor, shellclaude
modelstring or nullnull (the agent's own default)
permissionModedefault, acceptEdits, plan, bypassPermissions, dontAsk, autoauto
taskPermissionModesame values; for tasks Styx starts itself (Run locally, Deploy, Tech debt audit, merges)bypassPermissions
effortlow, medium, high, xhigh, max, ultra or nullnull
autoApproveEditsbooleanfalse
mayRequestTargetsboolean: May request targets starts on in New tasktrue
notifyWhenNeedsMeboolean: Notify when it needs me starts on in New tasktrue
perAgentobject keyed by agent, each { "model" }Accepted but ignored.

permissionMode values are shown in the app as Ask each time, Accept edits, Plan mode, Bypass permissions, Don't ask and Auto.

policies

Object. Extra access rules for the project.

FieldTypeNotes
extraarray of rulesSee below.
disabledBuiltinsarray of stringsAccepted but ignored.

Each rule in extra:

FieldTypeNotes
idstring1–64 characters: letters, digits and . _ : -.
ruleobjectOne of the three shapes below.
ruleTextstring1–200 characters. How the rule reads in Approvals › Policies and the audit log.
enabledbooleanOptional, default true.

rule shapes. match narrows which targets a rule covers: any of provider (array), env (array) and targetIds (array); a field you leave out matches everything.

  • { "kind": "auto-approve", "match", "scopes", "duration" }: grant without asking. scopes is a non-empty array of read, write, deploy, delete; duration is once, 1h, session or always.
  • { "kind": "ask", "match", "scopes", "requireMfa" }: always ask for these scopes, with Touch ID, Windows Hello or your system password if requireMfa is true.
  • { "kind": "idle-expiry", "match", "idleMs" }: end a grant after idleMs milliseconds without use.

worktrees

FieldTypeDefaultNotes
baseBranchstringmainThe branch lanes start from and land in.
branchPrefixstringagent/Prefix of each task's branch.
locationsibling or insidesiblingsibling: <parent of the repo>/.styx/worktrees/<repo>/<branch>. inside: <repo>/.styx/worktrees/<branch>.

shell

FieldTypeDefaultNotes
windowspowershell or wslpowershellWindows only. The shell this project's terminals, shell tasks, Run locally and deploy commands use. STYX_WIN_SHELL overrides it (see Environment variables).

lineEndings

auto, lf or crlf. Accepted but ignored.

dev

How to run the app locally, for Run locally and Preview. Usually written by Styx once an agent works it out.

FieldTypeNotes
commandstringThe command that starts the app, run from the project root.
urlstringThe URL it serves. Only localhost, 127.0.0.1 or [::1] over http or https is used; anything else is ignored.
platformweb, ios, androidWhat the command runs on. Leave it out for a web app.
devicestringUp to 120 characters. The simulator or emulator name, such as iPhone 17 Pro.
appIdstringUp to 200 characters. The bundle id or package, such as com.acme.shop.

A command that looks like it carries a secret (such as API_KEY=… pnpm dev) is run but never written to the file.

checks

What proves the work is good. Land runs it in the lane before merging, and Styx runs it before it commits a merge it resolved. Usually written by Styx when the task's agent works it out at the project's first landing; editable in Settings › Agent defaults › Checks before landing.

FieldTypeNotes
commandstringThe command, run from the root of the lane, such as pnpm typecheck && pnpm test. Blank means not known.

env

FieldTypeDefaultNotes
filesarray of strings[".env.local"]Accepted but ignored.
shareWithAgentsper-grant, always, neverper-grantAccepted but ignored.

Styx doesn't read .env files or hand them to agents. Agents reach targets only through grants; see How access works.

What is never in the file

  • Secrets. A key whose name contains secret, token, password, passphrase, private_key / private-key / privatekey or credential, at any depth, makes the whole file invalid (credentialRef is the one exception). Credentials live in the keychain.
  • Settings that are about this machine or this person: the target Policy you choose in Settings, deploy commands, the lane settings in Agent defaults (fetch before cutting a lane, bringing in the base branch, merging, landing on its own), and every App setting. They're kept in Styx's local database, so a teammate's commit can't turn on landing by itself for you, and reading the file again never changes them.
  • Built-in access rules and per-agent models. policies.disabledBuiltins and agents.perAgent are accepted so older files still load, but Styx ignores them: built-in rules are switched on and off in Settings › Policies on each machine, and a new task's model is agents.model.

Validation and versioning

  • The file is checked when Styx reads it. If it isn't valid JSON or doesn't match the schema, Styx logs why and keeps the settings it had.
  • Keys Styx doesn't know are kept when it rewrites the file, so a newer Styx's fields survive an older one.
  • Styx writes known keys in a fixed order, then unknown keys sorted, with 2-space indentation and a trailing newline, so diffs stay small.
  • The format is version 1. A future format will raise version.