Create and run locally

Local direct run is the normal starting point. Use it to prove selected source and the observable surface before any formal publish path.

Local development loop

Step	Command	Proves
1. Create	`arc blocklet create` / `init`	Package scaffold exists
2. Validate	`arc dsl validate` + `arc blocklet check`	DSL and profile contract
3. Run	`arc blocklet run` or `arc service start --blocklet`	Local HTTP surface
4. Accept	Browser on printed URL	Visible result
5. (Later) Build / publish	`arc blocklet build`, then a separate publish path	Artifact / release — not step 1

Local loop from create through validate, run, browser acceptance, then optional build and publish

Validate and run locally first. Publish and remote deploy are a separate path after acceptance.

1. Create a package

# Manifest only
arc blocklet create ./demo-basic --recipe basic --name demo-basic

# Tiny complete app (web + AUP + agent + settings)
arc blocklet create ./demo-min --recipe minimal-app --name demo-min

arc blocklet init is an alias for create (same flags).

Verified outputs (2.0.0-beta.28):

Created blocklet.yaml with did: "did:blocklet:demo-basic"

Created minimal app blocklet "demo-min" with 18 file(s).
Next: arc dsl validate /…/demo-min

basic tree:

demo-basic/blocklet.yaml

minimal-app includes (among others) blocklet.yaml, pages/index/…, .web/components/…, .aup/app.aup, agents/app-agent/…, and seed/settings/….

Options:

Flag	Meaning
`[dir]`	Target directory (default: cwd)
`--name <name>`	Blocklet name / id basis (default: directory name)
`--recipe` / `--template`	`basic`, `blank`, `blog`, `agent`, `minimal-app`, `agent-workspace`, `support-community`

Discover recipes:

arc blocklet recipe list
arc blocklet recipe explain basic

2. Validate before serving

arc dsl validate ./demo-min
arc blocklet check ./demo-min --profile minimal-app

Verified:

Passed DSL validation
  path: /…/demo-min
  files: 16

Passed blocklet check (minimal-app)
  dir: /…/demo-min
  AUP pages: agent, home, settings
  web sections: 1
  agents: 1
  settings files: 5

For a basic package:

arc blocklet check ./demo-basic
# Passed blocklet check (basic) — AUP pages (none), web 0, agents 0, settings 0

Match --profile to the recipe you used for complete-app recipes. Default profile is basic.

Optional format gate (may fail on freshly scaffolded DSL until formatted):

arc dsl lint ./demo-min
# If format_changed: arc dsl format --write ./demo-min

3. Run locally (preferred paths)

A. Single Blocklet: `arc blocklet run`

arc blocklet run ./demo-min

Verified:

Serving blocklet "demo-min" on port 4941
  http://demo-min.localhost:4941/
  http://localhost:4941/?blocklet=demo-min  (Safari / universal)

arc blocklet run reuses or starts the seed instance (default, port 4900). If that port is already taken by something you do not own, start a named instance instead (port auto-assigns). ARC_SERVICE_PORT still exists but only affects the seed instance. Do not stop a daemon you did not start.

To keep the source on the instance across restarts, use arc service start --instance <name> --blocklet ./demo-min.

B. Cold start with explicit path: `arc service start --blocklet`

arc service start --instance demo --blocklet ./demo-min --port 4939

Omit --port on a named instance to let the kernel assign one. Pinning 4939 matches the captured dump below.

Verified:

Starting AFS service...
  Extra blocklet dirs: /…/parent
AFS Service started
  PID:  …
  Port: 4939
  Blocklet: demo-min
    http://demo-min.localhost:4939/
    http://localhost:4939/?blocklet=demo-min (Safari / universal)

Both forms print a subdomain URL and a query URL (?blocklet=). Prefer the subdomain host when your browser resolves *.localhost. Use the query form when it does not (some Safari setups).

C. What to open

curl -sS -o /dev/null -w "%{http_code}\n" \
  -H "Host: demo-min.localhost:4939" \
  http://127.0.0.1:4939/
# 200

Open the printed URL in a real browser. Check layout at a wide and a narrow viewport when the surface matters.

Isolation for throwaway tests

ARC_HOME is retired. Use a named instance and --home:

export ARC_INSTANCES_DIR=/tmp/arc-instances-demo
arc service start --instance demo --home /tmp/arc-home-demo --blocklet ./demo-min
# … accept …
arc service stop --instance demo
arc service rm --instance demo

Stop only the temporary named instance you started. Do not stop the seed daemon on :4900 unless you started it.

Commands that are not a local app run

Command	What it actually does
`arc blocklet dev [dir]`	Scans directory conventions; prints mounts/content type. No HTTP server.
`arc blocklet build [dir]`	Writes `dist/`. Does not open a browser surface.
`arc deploy <path> --server …`	Remote DID Space publish path — not local acceptance
`arc deploy <path> --publish`	Local developer DID Space publish — separate from direct run; may require snapshot secrets

Prefer these local paths

Goal	Prefer	Avoid as first step
Day-to-day acceptance	`arc blocklet run` or `arc service start --blocklet`	DID Space deploy
CI / isolated check	`check` + `build` + optional headless HTTP probe	Shared production daemon
Multi-blocklet monorepo parent	`arc service start --instance <name> --blocklet <parent>`	Registering into an unknown shared daemon without isolation

Continue to Check, build, and inspect for the artifact chain, or Author to change package contents.

Local development loop

1. Create a package

2. Validate before serving

3. Run locally (preferred paths)

A. Single Blocklet: arc blocklet run

B. Cold start with explicit path: arc service start --blocklet

C. What to open

Isolation for throwaway tests

Commands that are not a local app run

Prefer these local paths

A. Single Blocklet: `arc blocklet run`

B. Cold start with explicit path: `arc service start --blocklet`