#Run your first Flow
Run a small method, read its result, and change what it does. This first Flow uses code and needs no Agent account. Next, you will call the same method from an application.
A Flow is a reusable method with an input, an outcome, and output. Jig runs its accepted revision with reviewed powers and limits. The method can use code, Agent judgment, or both.
#Before you start
Use a supported Linux or Mac host and npm.
Linux may need administrator configuration.
The qualified Mac path needs no sudo or administrator setup.
Jig refuses missing execution support instead of weakening its boundary.
Install the developer alpha:
npm installs Jig's exact Bun runtime dependency. You do not need a separate Bun installation for this tutorial. For source development, use the development instructions.
#1. Create the project
init creates ordinary editable source, including jig.ts, a greeting Flow, and an empty Bindings directory.
It installs nothing, makes no network requests, and approves nothing.
Open flows/hello/FLOW.ts:
The generated flows/hello/package.json declares the exact FLOW SDK revision tested with this Jig build.
Keep that dependency beside the Flow.
An application-root dependency does not replace the Flow's declaration.
#2. Review and approve
Inspect the generated source with your editor. Read the displayed package changes, execution policy, and available targets. The summary does not replace source review.
The resolution flag permits dependency-selected network requests before approval. Declining cannot undo those requests. It grants no network access to Runs and does not update supplied dependency locks. See dependency preparation before using it with unfamiliar packages.
Jig then asks:
Enter y to authorize that revision.
Declining leaves it unapproved.
Review prepares and retains dependencies privately, so this tutorial needs no per-Flow installation.
#3. Run and read the result
After approval:
Expect these fields in the result:
Additional fields report diagnostics, delivery, and cleanup.
status describes execution.
outcome describes the method's answer.
Other methods can complete successfully with outcomes such as blocked or limit.
Your application must inspect both.
Terminal stdout shows a readable result.
Redirected stdout or --json carries machine-readable JSON.
Stderr carries diagnostics and status.
This result-only method creates no result packet unless you request one with --out.
#4. Change the greeting
In flows/hello/FLOW.ts, replace Hello, with Welcome,.
Review the change and run again:
Approve only after inspecting the source change.
Expect {"message":"Welcome, Ada!"}.
Until approval, Runs continue using the previously accepted revision.
Code edits can need fresh dependency resolution when no authored lock exists. An unchanged review reuses admitted bytes. Manage dependencies explains authored locks and reusable libraries.
#If the first run fails
For host support, review, input, or execution failures, see Troubleshooting.
Ctrl-C requests cancellation. Wait for cleanup before starting new work. Do not automatically repeat an interrupted or uncertain operation.
#Continue from the result
Call this Flow from your application to consume its output from code. Then choose an Agent and compose methods. The contact importer demonstrates code, Agent, and mixed implementations behind one calling boundary.
For Agent-assisted development, install the FLOW and Jig authoring skills. See How Jig works for the responsibilities behind review, execution, and cleanup.
#Supported host
Jig qualifies Linux x86_64 and selected native Macs. It checks the exact host mechanism before execution and refuses unqualified kernels or missing support.
On Linux, Jig is developed primarily on NixOS and qualified in automated CI on provisioned Ubuntu 24.04 x86_64. This host needs:
- 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, andpidscontrollers. - A systemd user manager supporting transient scopes with
Delegate=yes. - Unprivileged user, mount, PID, network, IPC, UTS, and cgroup namespaces.
On Mac, Jig requires native Apple Silicon and macOS 15 or newer. It checks the required kernel mechanisms on the running host and refuses missing enforcement. Intel Macs and Rosetta execution are unsupported. Exact OS patch builds are recorded for diagnosis rather than used as a support allowlist.
Install through the same npm command above. npm selects the matching pinned Bun runtime. No privileged
helper, managed execution account, separate Bun installation, or sudo is
required. Jig uses a private native sandbox and an owned process coalition to
contain and stop work. Resource limits are supervised and sampled on Mac, so
CPU, memory, and process use can briefly exceed the requested ceiling before
Jig terminates the scope. See the security boundary
when deciding whether this tradeoff fits your workload.
Linux and Apple Silicon checks must pass before a release is published. Mac release qualification requires complete native and installed-consumer checks on macOS 15 and macOS 26 against the same candidate. Per-host prerequisite probes do not certify every other OS build. See the Mac qualification policy.
Jig's host-tool lookup currently uses /usr/bin, /bin, and
/run/current-system/sw/bin, not your shell's PATH.
If Bubblewrap is installed elsewhere, configure its absolute path before review.
See host configuration for the command.
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. Automated CI conformance on NixOS
remains unconfigured.
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.