algal.cloud
Quickstart

Quickstart

Create a habitat, run a program that waits for a message, post it one, and replay the run.

Early access (test mode). Payments run in Stripe test mode and no card is charged. Accounts, limits and prices may change before launch.

Before you start

  • curl and jq on your path.
  • An early-access API key in ALGAL_KEY. Keys start with ak_ and are issued when your early-access account opens.

Run the blocks in order in one shell. Each block uses variables set by the ones before it. The example program is quickstart-bundle.json.

  1. Point your shell at the API

    Every request below reads these variables. The key only ever lives in your environment.

    Point your shell at the API (bash)
    export ALGAL_API="${ALGAL_API:-https://api.algal.cloud}"
export ALGAL_SITE="${ALGAL_SITE:-https://algal.cloud}"
: "${ALGAL_KEY:?set ALGAL_KEY to your early-access API key}"

  2. Create a habitat

    A habitat holds your programs, their mailboxes and the record of every run.

    Create a habitat (bash)
    HABITAT=$(curl -fsS -X POST "$ALGAL_API/v1/habitats" \
  -H "Authorization: Bearer $ALGAL_KEY" -H "Content-Type: application/json" \
  -d '{"name":"quickstart"}' | jq -r .habitatId)
echo "habitat $HABITAT"

  3. Upload a program

    The example program waits on a mailbox and echoes the first message it receives. Upload its bundle; the response names the program by its content digest.

    Upload a program (bash)
    curl -fsS "$ALGAL_SITE/examples/quickstart-bundle.json" -o quickstart-bundle.json
ROOT=$(curl -fsS -X PUT "$ALGAL_API/v1/habitats/$HABITAT/bundles" \
  -H "Authorization: Bearer $ALGAL_KEY" -H "Content-Type: application/json" \
  --data-binary @quickstart-bundle.json | jq -r .root)
echo "program $ROOT"

  4. Open a mailbox

    A mailbox returns two capabilities: one the program receives on, and one anyone holding it can post to.

    Open a mailbox (bash)
    MAILBOX=$(curl -fsS -X POST "$ALGAL_API/v1/habitats/$HABITAT/mailboxes" \
  -H "Authorization: Bearer $ALGAL_KEY" -H "Content-Type: application/json" \
  -d '{"name":"inbox"}')
RECEIVE=$(echo "$MAILBOX" | jq -r .capability)
SEND=$(echo "$MAILBOX" | jq -r .send)

  5. Start the program and let it wait

    The process gets the receive capability as its input. The first scheduling pass runs it until it waits on the empty mailbox.

    Start the program and let it wait (bash)
    jq -n --arg root "$ROOT" --arg inbox "$RECEIVE" \
  '{name:"waiter", manifest:$root, args:{src:{inbox:$inbox}}}' > process.json
curl -fsS -X POST "$ALGAL_API/v1/habitats/$HABITAT/processes" \
  -H "Authorization: Bearer $ALGAL_KEY" -H "Content-Type: application/json" \
  --data-binary @process.json | jq -r .status
curl -fsS -X POST "$ALGAL_API/v1/habitats/$HABITAT/schedule" \
  -H "Authorization: Bearer $ALGAL_KEY" -H "Content-Type: application/json" \
  -d '{}' | jq -c '.outcomes'

  6. Send it a message

    Posting to the send capability needs no API key, only the capability and an Idempotency-Key. Sending the same key again returns the same delivery id instead of a second message.

    Send it a message (bash)
    DELIVERY=$(curl -fsS -X POST "$ALGAL_API/m/$HABITAT/$SEND" \
  -H "Content-Type: application/json" -H "Idempotency-Key: quickstart-1" \
  -d '{"hello":"habitat"}' | jq -r .deliveryId)
AGAIN=$(curl -fsS -X POST "$ALGAL_API/m/$HABITAT/$SEND" \
  -H "Content-Type: application/json" -H "Idempotency-Key: quickstart-1" \
  -d '{"hello":"habitat"}' | jq -r .deliveryId)
test "$DELIVERY" = "$AGAIN" && echo "delivered once: $DELIVERY"

  7. Watch it finish

    The delivery wakes the program. A scheduling pass runs it to completion; the status call confirms it.

    Watch it finish (bash)
    for attempt in 1 2 3 4 5; do
  curl -fsS -X POST "$ALGAL_API/v1/habitats/$HABITAT/schedule" \
    -H "Authorization: Bearer $ALGAL_KEY" -H "Content-Type: application/json" -d '{}' > /dev/null
  STATUS=$(curl -fsS "$ALGAL_API/v1/habitats/$HABITAT/processes/waiter" \
    -H "Authorization: Bearer $ALGAL_KEY" | jq -r .status)
  [ "$STATUS" = "complete" ] && break
  sleep 1
done
echo "status $STATUS"; test "$STATUS" = "complete"

  8. Replay the run

    Every run keeps a record you can replay. The verify route replays it from the stored receipts and reports whether the result matches.

    Replay the run (bash)
    curl -fsS "$ALGAL_API/v1/habitats/$HABITAT/verify/waiter" \
  -H "Authorization: Bearer $ALGAL_KEY" | jq -e '.ok == true'

Next