Skip to main content

​
Getting started

No. You describe what you want in conversation and JoyStream turns it into a specification, a reviewable plan, and a safe run. That’s the point of the product — the person who owns the work should be able to build and evolve the agent that does it.The CLI is one way to reach the platform. The web UI is another.
That covers macOS and Linux. Run it again to upgrade. See Install the CLI for the manual download, checksums, and the macOS .pkg.
macOS on Apple Silicon and Intel, and Linux on x86_64. The installer detects which one you’re on.
No. Run jstm login and you’re working. There is no config file to create and nothing to point at a server.A config file is only involved in self-hosting. See Configuration.
No. The .pkg is signed with our Developer ID, notarized by Apple, and stapled, so it installs with no Gatekeeper prompt even offline. The install script fetches the binary directly, which is also unaffected.
Re-run the installer:
To pin a version, set JSTM_VERSION.

​
Building agents

No. Exiting always leaves your spec as a draft — that’s deliberate, so a closed terminal can never create or change an agent by accident.Resume with jstm agent plan <session-id>, or commit with jstm agent plan done <session-id>.
It shows your sessions newest first, with their status.
Correct. save, done, quit, and exit all only exit the chat. The only command that commits is jstm agent plan done <session-id>, run after you leave.
Not the chat itself — it requires a real interactive terminal and fails fast rather than degrading.To create a draft non-interactively:
Conformance asks whether the built package is well-formed against the agent spec. Readiness asks whether the skills it needs can actually execute here — servers reachable, credentials present.A package can be perfectly conformant and completely unable to run.
No. The CLI runs the two deterministic lanes, schema and spec_conflict, which need no key and no network. The semantic judge lane is optional and isn’t run by the CLI.

​
Running agents

Dry Run executes end to end with side-effecting actions held back — nothing outside JoyStream changes. Pilot is controlled real execution with limited scope, access, volume, or audience. Live is approved production execution.Pilot and Live both prompt for confirmation.
The earlier name for Dry Run. The stage is the same.
Check the mode. Dry Run holds side effects back by design.
A BEST_EFFORT step records its failure and lets the run continue, so a run can complete with a failure inside it. Check the stories, not only the run status.
Pass an idempotency key. Re-sending the same key won’t start a second run.
The stream times out after 300 seconds. The run keeps going — rejoin with jstm agent run show.

​
Scheduling and triggers

All schedules are evaluated in UTC. There is no per-schedule timezone in this version, so 0 9 * * * means 09:00 UTC.
schedule set sends the run mode on every call and defaults it to dry_run. Changing only --cron reverts a live schedule.Always repeat --env live:
No. It fires the most recent missed occurrence once on recovery, then resumes normally.
No, an installation id. Get it from jstm agent installation list.

​
Credentials and access

A personal credential is shadowing the shared one. Credentials resolve from the most specific tier outward — personal, then workspace, then org.
That sign-in grants public access only. Private repositories need a personal access token with the repo scope, connected under Settings → Connections.
No. Personal vaults are excluded from the org audit entirely.
No surface returns token material — not the API, not the CLI, not the UI. You see providers, status, and who connected them, never secrets.
They were replaced by vault scope, which sets a credential’s availability in one choice: --scope all for org-wide, or --scope selected with repeatable --workspace.vault grant list still exists, as a read.

​
Teams and sharing

Membership in the workspace, as a member — not scoped to the shared object alone. Share deliberately.
No. Move it to a team workspace first:
Agents in a team workspace stay. Agents in their personal workspace leave with them — which is why work that matters to the team should be moved to a team workspace early.After removing someone, run jstm vault audit and reconnect any credential they had connected.
Team handles are unique within an organization, not across all of them.
Or use the fully qualified form, acme-corp/platform.
Visibility (ORG_VISIBLE) is for a capability the whole organization should find and install. Sharing is for one person and one object.

​
The CLI

No, it’s per command. Most read and write commands support it. A few don’t, because their output is interactive or a single line — connection test, connection add, connection remove, trigger delete, trigger webhook-url, org invite, org remove, the profile email subcommands, and jstm commands.
Yes. Results go to stdout and all diagnostics to stderr, so the JSON stream stays clean:
A usage error — an unknown flag, a missing argument, or an invalid command form. A bare jstm agent plan is the common one; creating an agent is always explicit.
Yes. JOYSTREAM_CONFIG_DIR gives each one its own session:
Set the same value for every command in that profile. See Configuration.
Set JOYSTREAM_TOKEN. It takes precedence over the session file, so no interactive login is needed.
It always reflects the version you have installed.

​
Still stuck?

Email support@joystream.ai, and include the output of JOYSTREAM_DEBUG=1 jstm <your command>.