AI agents and the Falak skill
The Falak skill is an Agent Skill: a SKILL.md with instructions, plus reference files, that teach an AI coding agent (Claude Code, Codex, Cursor and other tools that read SKILL.md) to operate Falak through the falak CLI, falak.yaml and the REST API. It covers deploys and rollbacks, config as code, secrets, functions, database containers, templates, logs, consoles and network tools, and says which actions need a human’s confirmation. It shipped with v0.19.0.
falak/├── SKILL.md # when to use it, ground rules, core workflows (loaded when the skill triggers)└── references/ ├── cli.md # every falak command, flag, default and exit code ├── config.md # the falak.yaml schema (v1), condensed ├── api.md # tokens, abilities, the main /api/v1 endpoints ├── workflows.md # recipes: repo, template, databases, functions, secrets, domains, logs, consoles, net ├── safety.md # destructive actions, secret handling, least-privilege tokens └── llms.txt # a short index for tools that read llms.txtThe agent reads SKILL.md when a task mentions Falak, and opens a reference file only when it needs it. The skill does not administer the control plane host itself: that is falak-ctl, run as root on the host.
Install
Section titled “Install”The falak CLI ships a copy of the skill and writes it for you (falak help lists skill install; run falak update first if it doesn’t):
falak skill install # ~/.claude/skills/falak (your user, every project)falak skill install --project # .claude/skills/falak in the current directory (commit it for your team)falak skill install --dir ~/.codex/skills/falak # any other agent's skills folderIt refuses to overwrite existing files; --force replaces them, so run it again after falak update to refresh the skill. --json prints the directory and the files written. --user is the default.
Copy the folder from the repository (or a release’s source archive):
git clone --depth 1 https://github.com/falak-sh/falak /tmp/falakcp -R /tmp/falak/skills/falak ~/.claude/skills/ # user-wide, Claude Codecp -R /tmp/falak/skills/falak .claude/skills/ # one project, Claude CodeThe same files are published on this site under /skills/falak/: SKILL.md, and in references/ cli.md, config.md, api.md, workflows.md, safety.md and llms.txt.
- Claude Code loads skills from
~/.claude/skills/<name>/SKILL.mdand.claude/skills/<name>/SKILL.md. Start a new session after installing. - Codex and other
SKILL.mdtools: put the same folder in the tool’s skills directory (for Codex CLI,~/.codex/skills/at the time of writing; check your tool’s docs), or usefalak skill install --dir. - Tools without skill support (Cursor rules, a system prompt, an MCP server’s instructions): point them at the raw files, or paste
SKILL.mdand the reference you need./llms.txtlists them too.
Give the agent credentials
Section titled “Give the agent credentials”The skill drives the falak CLI, so the agent needs a working falak and credentials. Install the CLI with curl -fsSL https://falak.sh/install-cli.sh | sh, then pick one:
You sit next to the agent. Log in yourself, once:
falak login --url https://falak.example.comThe browser sign-in stores a token named CLI — <host> with your role’s permissions in the CLI’s credentials file. It expires 90 days after its last use (a year after the login at most), and falak logout revokes it. Convenient, but the agent can then do everything your role allows.
The agent runs unattended, or you want to limit it (recommended). Create an API token for it in Settings → API tokens, with only the abilities it needs and an expiry, and pass it through the environment:
export FALAK_URL=https://falak.example.comexport FALAK_TOKEN=… # from your secret manager; never commit it or paste it into the chatfalak whoami # user, organization, role, token name and abilitiesOr store it for the CLI with printf '%s\n' "$FALAK_TOKEN" | falak login --url "$FALAK_URL" --token-stdin. falak logout then forgets it but doesn’t revoke it: revoke pasted tokens in Settings → API tokens. FALAK_CONFIG_DIR keeps an agent’s credentials apart from yours.
Least privilege
Section titled “Least privilege”A token belongs to one organization, and a request passes only when the token has the ability and its owner’s role has the permission, so an agent never does more than the person who created its token. Suggested sets:
| The agent should | Abilities |
|---|---|
| Look around (read-only) | sites.view, servers.view, deployments.view, telemetry.view, projects.view, databases.view, functions.view, config.view |
| Deploy and roll back existing sites (CI) | sites.view, deployments.view, deployments.create, deployments.rollback |
Work with falak.yaml |
projects.view, config.view, config.apply, secrets.view, secrets.manage (+ deployments.view) |
| Deploy functions | functions.view, functions.deploy, deployments.view, deployments.create, telemetry.view |
Edit a site’s .env |
sites.view, sites.env.view, sites.env.manage |
| Deploy templates | projects.view, projects.manage, templates.view, sites.create, deployments.create |
Keep these for humans unless you decided otherwise: *, config.approve (approving risky changes), config.destroy (deleting data from falak.yaml), databases.manage (deleting database containers), sites.delete, servers.delete, secrets.reveal, terminal.open (consoles), network.tools and network.capture. Without them the agent asks you instead, which is what the skill tells it to do anyway. See Permissions.
What the skill tells the agent
Section titled “What the skill tells the agent”- Use the CLI with
--jsonand branch on exit codes:3deployment failed,4a newer function version,5invalidfalak.yaml,6waiting for an approval,7drift. - Never print secrets: tokens,
.envcontents, secret values or database passwords. Pass secrets on stdin and reference them infalak.yaml. - Ask before destructive or irreversible actions, and show the exact command first: deletions,
--allow-destroy, approving risky runs,env push, rotating or deleting secrets, production rollbacks, consoles and packet captures, restores, and anything on the control plane host. - Look before changing:
validate→plan→applyfor config as code;falak sites show,falak planandfalak driftchange nothing.
Keeping it current
Section titled “Keeping it current”The skill documents the CLI and API of the matching Falak release, checked against the source. falak skill install --force after falak update brings it in line with your CLI.