#Get started with Jig

Jig runs methods that use code, Agent judgment, or both through the same callable boundary. This guide starts with a small code-only Flow and the review-and-run loop. Then use one caller with three implementations to see how Agent work fits into the same model.

#Install

Use a supported Linux host. The qualified environment is Ubuntu 24.04 x86_64 with the isolation prerequisites listed below; a stock Linux installation may need host configuration. If you do not administer the host, ask its administrator to check that list before installing. Jig reports missing execution support rather than weakening isolation.

Install the CLI:

npm install --global @jigging/jig@alpha

npm also installs Jig's exact Bun runtime dependency. You do not need a separate Bun installation for this tutorial. To use a source checkout, follow the development instructions.

#Your first Flow

Create a project, review its changes, approve it, then run its greeting Flow:

jig init hello-jig
cd hello-jig
jig review --allow-resolution-network
jig run flow:flows/hello --input '"Ada"'

During jig review, inspect the generated source with your editor and read the displayed changes and policy. The summary does not replace source review. The terminal then asks:

Approve this exact revision for execution? [y/N]

Enter y to authorize that revision, or decline to leave it unapproved. Only run the next command after approval.

init writes ordinary editable files: jig.ts, flows/hello/FLOW.md, flows/hello/package.json, and flows/hello/flow.ts, plus a README and empty Bindings directory. It installs nothing, makes no network requests, and approves nothing. Use jig init --bare <directory> when you want an empty project instead.

The greeting names the exact FLOW SDK revision tested with its Jig build, not a moving registry tag. Review resolves and retains its dependencies privately, so no per-Flow bun install is needed. --allow-resolution-network permits dependency-selected network requests before approval; declining cannot undo those requests. It does not give Runs network access. Supplied dependency locks remain frozen. See dependency review for reusable locked packages.

The generated flow.ts is ordinary SDK code you can edit:

import { handle } from "@jigging/flow";

await handle(async (run) => {
  const name = typeof run.input === "string" ? run.input : "world";
  return { outcome: "done", output: { message: `Hello, ${name}!` } };
});

The result includes status: "succeeded", outcome: "done", and output: { "message": "Hello, Ada!" }, alongside bounded diagnostics. The input is a JSON string; other input values use "world". This Flow needs no Agent configuration.

#Make one change

In flows/hello/flow.ts, change Hello, to Welcome,. Review and run again:

jig review --allow-resolution-network
jig run flow:flows/hello --input '"Ada"'

Approve the source change only after reviewing it. The new output contains {"message":"Welcome, Ada!"}. Until you approve, runs continue using the previously accepted version. The network flag has the same dependency-resolution meaning described above; it does not authorize the Flow to access the network.

You have now created, run, and adapted a method. Next, add a support-reply Agent to this same project, or see one caller use code, an Agent, or both. The method boundary stays consistent as the implementation changes. Read how Jig works for the architecture behind it, or try a tested patch for a larger application.

#Review, run, improve

jig review leads with added, changed, and removed packages, Bindings, and execution policy, then lists the targets you can run. Changed policy is shown in full; unchanged policy is omitted. When proposing a change, use jig review --details to inspect complete current and proposed policy. If Agent capabilities are used, the review also names the selected non-secret host Agent configuration. Inspect the source with your usual tools, then approve the review. In a noninteractive environment, --yes records your explicit approval; it does not grant resolution-network permission.

jig run uses the approved revision. Edit the source and review again to run your changes. Declining a review leaves the previously approved revision intact. For the unlocked greeting, repeat jig review --allow-resolution-network after editing; code-only edits can require fresh resolution too. An unchanged review reuses the admitted bytes. An authored lock avoids fresh dependency selection.

Use flow:<path> for a package or binding:<id> for a configured invocation. Use jig inspect to list the approved targets, or jig inspect <target> to read a target's retained schemas and configuration without performing a review. Inspection also reports whether current local execution identities match that approval, require review, or could not be verified. It does not check source edits or promise a later Run will succeed. A Binding supplies application settings and exact dependencies; see project authoring. Omitting --input supplies {}. Use @FILE for JSON input from a file and --timeout 2m for a longer Run. See execution policy for current limits and lifecycle guarantees.

#Read the result

The greeting returns execution status, the method's outcome, and its output. Other methods can complete execution successfully while returning an application outcome such as blocked. Inspect the outcome as well as the CLI exit status.

Terminal stdout shows a readable result; redirected stdout or --json carries the machine-readable result. Stderr carries diagnostics and status. Ctrl-C requests cancellation. Wait for cleanup before starting new work, and do not blindly retry an interrupted or uncertain operation.

See results and recovery for output delivery, scripting, protocol failures, and retained-state recovery.

#Next steps

Add a second Flow from the project directory:

jig new summarize

Edit flows/summarize/flow.ts and its FLOW.md, then use the ordinary jig review and jig run flow:flows/summarize path. This creates source only: no installation, approval, or execution. Default discovery includes the new directory; if you selected explicit members in jig.ts, add it there first. Dependency resolution still requires your explicit network permission when needed, as described in dependencies.

• Build your first Agent method in the project you just created.
• Compose code and Agent methods through one caller.
• Choose an Agent using an API or a supported local client.
• Work with files to capture inputs and export one result packet.
• Configure Jig for terminal appearance, startup verification, and operator settings.
• Manage dependencies for reusable Flow packages.
• Repair a project or handle a disputed charge.
• Choose a workflow structure for your application.

#Supported host

The alpha has independent host evidence on provisioned Ubuntu 24.04 x86_64. Other matching Linux hosts are not yet independently validated. Jig checks required capabilities and reports missing support.

• Linux x86_64, glibc 2.17 or newer, and an SSE4.2-capable CPU.
• Bubblewrap 0.12 or newer and GNU readlink -f.
• cgroup v2 with delegated cpu, memory, and pids controllers.
• A systemd user manager supporting transient scopes with Delegate=yes.
• Unprivileged user, mount, PID, network, IPC, UTS, and cgroup namespaces.

Jig's host-tool lookup currently uses /usr/bin, /bin, and /run/current-system/sw/bin. An absolute JIG_BWRAP_PATH selects another Bubblewrap installation. The host validates the selected tool; an invalid explicit selection fails rather than falling back.

On NixOS, enable programs.nix-ld.enable for npm's runtime binary. Jig resolves glibc through /run/current-system/sw/share/nix-ld/lib/ld.so and gives Runs only the required loader and libraries. Independent NixOS conformance remains unverified.

review and run acquire their delegated scopes without sudo. Jig verifies the package-local Bun runtime before execution. See the security boundary for isolation details and the private reporting channel.