Skip to content
grafOS docs

Quickstart

This walkthrough takes you from curl … install.sh | sh to a finalized run on a Tenura cloud cell in about five minutes. The example commands target AWS — pick whichever cloud you’ve onboarded (aws, gcp, or azure); the steps are identical.

What you need

  • A macOS or Linux machine.
  • A Tenura beta access code (request one at tenura.systems/request-invite).
  • A web browser to complete email verification — the rest is CLI.

1. Install the CLI

Terminal window
curl -fsSL https://get.tenura.systems/install.sh | sh

Expected:

Resolving latest stable version from https://releases.tenura.systems/stable/VERSION...


tenura-systems grafos installer


  Version:       0.1.2
  Target:        x86_64-unknown-linux-gnu
  Install root:  /home/you/.local
  Config root:   /home/you/.config/grafos


Downloading artifacts to /tmp/tmp.XXXXXX ...
Verifying minisign signature on SHA256SUMS...
Verifying minisign signature on grafos-0.1.2-x86_64-unknown-linux-gnu.tar.gz...
Verifying SHA-256 of grafos-0.1.2-x86_64-unknown-linux-gnu.tar.gz matches SHA256SUMS...


Unpacking...


grafos 0.1.2 installed at /home/you/.local/bin/grafos

The installer verifies a minisign signature on every artifact before writing anything to disk. If ~/.local/bin isn’t on your PATH, add it (the installer prints the line to add).

Confirm:

Terminal window
grafos --version
# grafos 0.1.2

2. Sign up + verify your account

If you have an access code already:

  1. Open https://tenura.systems/signup/ (or click the prefilled link from the approval email).
  2. Fill in your name, email, and access code; complete the Cloudflare Turnstile.
  3. Submit. You’ll get a verification email within a few seconds.
  4. Run the command in the email:
Terminal window
grafos account verify --url 'https://tenura.systems/verify?code=...&tenant=...'

Expected:

Verifying with https://api.tenura.systems...
Generating local signing key...
Binding signing key to tenant...


Account verified.
  tenant_id:         019df865-524f-7750-849e-19f8acd159d6
  scheduler_url:     https://scheduler.grafos.tenura.systems
  scopes:            tenant_user, dashboard_read, local_dev_run, cloud_run, billing_read
  token_expires_at:  1779198555 (in ~13 days)


Credentials stored at /home/you/.config/grafos/credentials.json (mode 0600).

You’re logged in. The credential is mode-0600 and contains a 13-day token plus a fresh local Ed25519 signing key.

3. Scaffold a project

Terminal window
mkdir my-first-grafos && cd my-first-grafos
grafos new sample
cd sample

Expected layout:

sample/
├── Cargo.toml
├── grafos.toml          # tasklet declarations + resource hints
├── README.md
├── src/
│   ├── lib.rs
│   ├── tasklets/
│   │   ├── metadata.rs
│   │   └── thumbnail.rs
│   └── ...
├── fixtures/
└── .grafos/

grafos new ships with two example tasklets — metadata (returns image metadata as JSON) and thumbnail (downscales an image). You’ll deploy metadata in this walkthrough.

4. Build the tasklets

Terminal window
grafos tasklet build

Expected:

Built 2 tasklet(s):
  thumbnail eb1824d3eb9a7879714b441f812adf91c0e0655c1031bb1c0ca02a43683a7e69 18274 bytes
  metadata  4dc9cb380feef014731716c0c9d8822ef8aefc96b2ecd43bd29fb7070e4d3004 27173 bytes

The hashes are SHA-256 of each WASM module. They go into the deploy manifest so the scheduler can verify what it admits.

5. Validate

Terminal window
grafos validate

Expected:

Computing source hash over 6 include pattern(s)...
  source_hash: 21eb094c4e6fbc45ea17486e8bfe693296fb661183eacbe07b8ee2d350d221a0
Running tests: cargo test --quiet


Wrote validation report → .grafos/validation.json
  tests: PASSED
  local    enabled
  aws      disabled
  gcp      disabled
  azure    disabled
  tasklets: 2
    thumbnail abi=tasklet-profile-v0
    metadata  abi=tasklet-profile-v0

This runs your tests and emits a validation report the dashboard reads. You don’t have to run validate before deploying — grafos deploy does its own checks — but running it locally is faster than waiting for a remote refusal.

6. Deploy on a cloud cell

Terminal window
grafos deploy run --provider aws --tasklet metadata --mem 32768 --json

Expected:

Deploying /tmp/.../sample:metadata (27173 bytes) to https://scheduler.grafos.tenura.systems...
{
  "artifact_manifest_hash": "sha256:15c1852116d440e92335581d74eeaadcbfd4889260f3c247a7f13a4c4f4b7dac",
  "assignment_id": "asg-run-deploy-171853644cb42b6cfdfc7dbdcd110b81-1",
  "cell_id": 1777420501,
  "control_mode": "outbound-work-channel",
  "exit_code": 0,
  "generation": 1,
  "provider": "aws",
  "run_id": "run-deploy-171853644cb42b6cfdfc7dbdcd110b81",
  "status": "ok"
}

Your tasklet ran on a cloud cell, persisted output artifacts, and finalized. exit_code: 0 is what you wanted.

7. Inspect the run

Terminal window
grafos runs show run-deploy-171853644cb42b6cfdfc7dbdcd110b81 --json | head -20
grafos artifacts run-deploy-171853644cb42b6cfdfc7dbdcd110b81 --json

Expected:

{
  "schema_version": 1,
  "context": "tenura-hosted",
  "scheduler_url": "https://scheduler.grafos.tenura.systems",
  "run_id": "run-deploy-171853644cb42b6cfdfc7dbdcd110b81",
  "output_dir": ".grafos/artifacts/run-deploy-...",
  "artifacts": [
    { "path": "response.json", "sha256": "sha256:a4325340...", "size_bytes": 157 },
    { "path": "output.b64",    "sha256": "sha256:4a75df04...", "size_bytes":  36 }
  ]
}

Both artifacts download with SHA-256 verification. response.json carries your tasklet’s exit code, run metadata, and the structured output. output.b64 is the raw output payload.

What just happened

You went from a clean machine to a verified, signed, lease-bound, capability-token-gated execution on a Pi5 fabric, in five minutes. Specifically:

  1. The installer verified minisign signatures on every artifact before writing anything.
  2. grafos account verify exchanged the email code for a hosted credential and bound a fresh Ed25519 signing key.
  3. grafos tasklet build produced WASM modules and SHA-256-hashed them.
  4. grafos deploy resolved the hosted scheduler URL from your credential, sent the manifest to the scheduler, the scheduler picked a healthy cell on the chosen provider, the cell’s CapBroker minted leases + tokens, the cell loaded the WASM under those tokens, ran your code, and persisted artifacts.

For the moving parts in detail, read Concepts. For the next step, pick a Cookbook recipe closest to what you want to build.