Skip to main content

ARC 2.0.0-beta.28

Create and run locally

Scaffold a Blocklet with arc blocklet create, validate it, and serve it with blocklet run or service start — no DID Space required.

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

StepCommandProves
1. Createarc blocklet create / initPackage scaffold exists
2. Validatearc dsl validate + arc blocklet checkDSL and profile contract
3. Runarc blocklet run or arc service start --blockletLocal HTTP surface
4. AcceptBrowser on printed URLVisible result
5. (Later) Build / publisharc blocklet build, then a separate publish pathArtifact / 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

bash
# 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):

text
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:

text
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:

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

Discover recipes:

bash
arc blocklet recipe list
arc blocklet recipe explain basic

2. Validate before serving

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

Verified:

text
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:

bash
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):

bash
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

bash
arc blocklet run ./demo-min

Verified:

text
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

bash
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:

text
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

bash
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:

bash
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

CommandWhat 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> --publishLocal developer DID Space publish — separate from direct run; may require snapshot secrets

Prefer these local paths

GoalPreferAvoid as first step
Day-to-day acceptancearc blocklet run or arc service start --blockletDID Space deploy
CI / isolated checkcheck + build + optional headless HTTP probeShared production daemon
Multi-blocklet monorepo parentarc 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.