Skip to content
EN
Get API key
Browse documentation

Guides

Deploy FlashData workloads

Run your app or agent's CLI tasks on Linux or Docker, then verify access and result reuse after a restart.

On this page

1. Choose the runtime

Use a Linux host with Bash and jq, and an owner API key with google_search permission. Run setup as the OS user that will execute the task. Create this private task folder for steps 1–4; file labels show any subfolders.

Create the task folder
umask 077
mkdir -p "$HOME/flashdata-tasks/deployment-check"
cd "$HOME/flashdata-tasks/deployment-check"

Install the native CLI first. Run command -v flashdata to find its absolute path, then set FLASHDATA_BIN to that path in runtime.sh. Set the profile name and persistent state path once here, then save the file.

runtime.sh
# runtime.sh — edit the executable and persistent state paths.
export FLASHDATA_BIN=/usr/local/bin/flashdata
export FLASHDATA_PROFILE=research
export FLASHDATA_STATE_DIR="$HOME/.local/state/flashdata-research"

run_flashdata() {
  env -u FLASHDATA_API_KEY "$FLASHDATA_BIN" "$@" \
    --profile "$FLASHDATA_PROFILE" \
    --state-dir "$FLASHDATA_STATE_DIR"
}

Check the selected runtime

Run from the task folder. run_flashdata is the helper saved in runtime.sh; all later commands use its profile and state directory. It ignores FLASHDATA_API_KEY so an environment key cannot replace the saved profile. Expect the CLI and jq versions.

Prepare persistent state · no API query
set -euo pipefail
umask 077
. ./runtime.sh
mkdir -p "$FLASHDATA_STATE_DIR"
chmod 700 "$FLASHDATA_STATE_DIR"
run_flashdata --version
jq --version

2. Install owner access once

If the profile already has owner access, skip the import and run the check below. Otherwise, mount an owner-key secret file readable by the service user and replace the example path with its location. The import reads it through stdin; Docker does not copy it into the image.

Point to the deployed secret file
export FLASHDATA_KEY_FILE='/run/secrets/flashdata_api_key'
Import and verify in the selected runtime
set -euo pipefail
. ./runtime.sh
: "${FLASHDATA_KEY_FILE:?Set the path to your mounted owner-key secret}"
run_flashdata auth login --api-key-stdin --non-interactive \
  < "$FLASHDATA_KEY_FILE"
run_flashdata auth status --json --non-interactive

Confirm the account and permission

The check prints the account ID, permitted sources and credential protection, then true. Confirm the account ID is the intended owner before continuing. access.json stays in the task folder for inspection.

Saved owner access · free check
set -euo pipefail
umask 077
. ./runtime.sh
run_flashdata auth status --json --non-interactive > access.json
jq '{accountId: .data.identity.identity.accountId,
     sources: .data.identity.permittedSources,
     credentialProtection: .data.credentialProtection}' access.json
jq -e '.ok and .data.accessVerified
  and (.data.identity.identity.recurringAllowed == true)
  and (.data.identity.permittedSources | index("google_search") != null)' access.json

Credential storage and persistent files

Inspect data.credentialProtection in auth status. Linux can use an unlocked Secret Service; a headless host or the container above may use an owner-only plaintext file. Keep the state directory private and persistent. Provision the deployed user separately from your laptop's encrypted profile.

KeepLocation
Credentials and run journalFLASHDATA_STATE_DIR
Input, receipts and resultsThe task folder; mounted as /work in Docker.

3. Validate the request and cost

Save request.json beside runtime.sh. The following check validates recurring access and the request, reads current pricing and compares it with the available balance. It submits no search and does not reserve credits. Continue only when the filter prints true.

request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
Check before the first paid task
set -euo pipefail
umask 077
. ./runtime.sh
run_flashdata account balance --json --non-interactive > balance.json
run_flashdata query --input request.json --mode realtime --dry-run --recurring \
  --run-id deployment-first-task --json --non-interactive > preflight.json
jq -e --slurpfile balance balance.json '
  .ok and .data.dryRun and .data.estimateAvailable
  and ($balance[0].ok == true)
  and any(.data.estimate.prices[]?;
    .source == "google_search" and .available == true
    and (.estimatedCredits | type == "number")
    and ($balance[0].data.availableCredits | type == "number")
    and .estimatedCredits <= $balance[0].data.availableCredits)
' preflight.json

4. Run once and verify reuse

Save deployment-check.sh below. With a new deployment-first-task run ID, the first execution submits one paid search; the second starts a new process and reads the saved result. If this ID already completed in the same profile, both attempts reuse it.

Save deployment-check.sh

Create deployment-check.sh beside runtime.sh and request.json in the private task folder on the host. Copy the complete script below into it and save it.

deployment-check.sh
#!/usr/bin/env bash
set -euo pipefail
umask 077
cd -- "$(dirname -- "$0")"
. ./runtime.sh
attempt=$(mktemp -d ./deployment-check.XXXXXX)
printf 'Attempt files: %s\n' "$attempt" >&2
cp -- request.json "$attempt/request.json"
if ! run_flashdata query --input "$attempt/request.json" --mode realtime --recurring \
  --run-id deployment-first-task --timeout 2m --json --non-interactive \
  --output "$attempt/result.json" \
  > "$attempt/receipt.json" 2> "$attempt/error.json"; then
  cat "$attempt/error.json" >&2
  exit 1
fi
jq -e '.ok == true' "$attempt/receipt.json" >/dev/null
jq -e '.source == "google_search" and .status == "done"
  and (.results[0].organic | type == "array")' "$attempt/result.json" >/dev/null
jq '{runId, cached, usage}' "$attempt/receipt.json"
printf 'Saved result: %s\n' "$attempt/result.json"

Run the saved check twice

Run from that host task folder as the same service user. Both processes load the runtime.sh saved in step 1.

Run, then restart the process
# A new run ID submits one paid search; a completed ID reuses its result.
bash deployment-check.sh

# New process; Docker uses a new container with the same mounts.
# Same account, input and state: cached: true, no new search.
bash deployment-check.sh

Verify the second receipt

For a new run, expect cached: false, then cached: true. Each attempt prints its deployment-check.XXXXXX folder and saves request.json, receipt.json and error.json, plus result.json on success. The cached receipt reports the original usage. A failed attempt keeps its files for recovery.

Second receipt · excerpt
{
  "ok": true,
  "runId": "deployment-first-task",
  "cached": true
}

Read the saved search result

Set ATTEMPT_DIR to the second successful folder printed above, for example export ATTEMPT_DIR='./deployment-check.ABC123'. These commands read local files only.

Receipt and source links
# Use one attempt folder printed by deployment-check.sh.
: "${ATTEMPT_DIR:?Set a saved deployment-check.XXXXXX folder}"
jq '{runId, cached, usage}' "$ATTEMPT_DIR/receipt.json"
jq '.results[0].organic[] | {title, link, snippet}' "$ATTEMPT_DIR/result.json"

Move from a deployment check to a recurring task

This check has a fixed run ID. For recurring work, give each intended occurrence its own ID and retain the selected runtime, account, input snapshots and state mounts. Adapt the recurring runner's query command to use run_flashdata so Docker tasks stay inside the container.

Check access from GitHub Actions

Use a trusted, persistent Linux runner with Bash, jq and the CLI profile already installed under the runner's OS user. Save this workflow in your application's repository. It checks the host CLI without running a paid task.

  1. Assign the flashdata-research label to that runner.
  2. Set repository variables FLASHDATA_BIN and FLASHDATA_STATE_DIR to its absolute paths, and FLASHDATA_PROFILE to the installed profile name.
.github/workflows/flashdata-check.yml
name: FlashData access check
on: workflow_dispatch
permissions: {}
concurrency:
  group: flashdata-research
  cancel-in-progress: false
jobs:
  verify:
    runs-on: [self-hosted, linux, flashdata-research]
    timeout-minutes: 5
    steps:
      - name: Verify the installed profile without a paid query
        shell: bash
        env:
          FLASHDATA_BIN: ${{ vars.FLASHDATA_BIN }}
          FLASHDATA_STATE_DIR: ${{ vars.FLASHDATA_STATE_DIR }}
          FLASHDATA_PROFILE: ${{ vars.FLASHDATA_PROFILE }}
          FLASHDATA_API_KEY: ""
        run: |
          set -euo pipefail
          : "${FLASHDATA_BIN:?Set the absolute CLI path}"
          : "${FLASHDATA_STATE_DIR:?Set the existing absolute state directory}"
          : "${FLASHDATA_PROFILE:?Set the installed profile name}"
          test -d "$FLASHDATA_STATE_DIR"
          "$FLASHDATA_BIN" auth status --profile "$FLASHDATA_PROFILE" \
            --state-dir "$FLASHDATA_STATE_DIR" --json --non-interactive |
            jq -e '.ok and .data.accessVerified
              and (.data.identity.identity.recurringAllowed == true)
              and (.data.identity.permittedSources | index("google_search") != null)'

Run the access check

After saving the workflow on the repository's default branch, open Actions → FlashData access check → Run workflow. Expect true and a successful check. Missing access or permission fails the job without submitting a search.

Keep execution state across jobs

An ephemeral runner starts without the original journal. Use durable application state or a persistent runner for paid recurring work. Reinstalling only the key cannot identify a previous job's submission. Keep the state directory and task outputs private; do not upload them as CI artifacts.

Rotate or revoke deployed access

Pause dispatch. In the task folder, point FLASHDATA_KEY_FILE at a replacement key for the same account and required sources, then run the commands below. Repeat the access check and deployment-check.sh; expect cached: true. Revoke the old key after verification and keep the profile and state directory.

Replace the key through stdin
set -euo pipefail
. ./runtime.sh
: "${FLASHDATA_KEY_FILE:?Point to the mounted replacement key for the same account}"
run_flashdata auth login --replace --api-key-stdin --non-interactive \
  < "$FLASHDATA_KEY_FILE"
run_flashdata auth status --json --non-interactive

Stop access completely

Pause the scheduler, revoke the key or agent connection in the console, then repeat the free access check. It must fail. Local logout alone does not revoke the server credential; already exported files remain on disk.

Deployment checks that fail

SymptomFix
Command not found / wrong CLI versionCheck command -v flashdata and FLASHDATA_BIN in runtime.sh. For Docker, rebuild and run the image's --version check.
Missing mount or permission deniedCreate the state and task folders on the Docker host, owned by the service UID/GID. Keep their paths stable.
replacement_requires_flagThe profile has a different saved key. Verify existing access first; use the rotation procedure for an intended replacement.
Cannot decrypt saved accessRun as the user that provisioned it, in the same credential-store environment. Provision access on a new destination instead of copying an encrypted laptop profile.
Cost check returns falseInspect balance.json and preflight.json. Require an available price, source permission and enough balance before submitting.
run_account_mismatchCheck the selected account and API origins. Restore the original access; do not rename the run to bypass recovery.
run_id_input_conflictRestore the original request from the attempt's request.json. Use a new run ID only for an intended new paid task.
CI stays queuedCheck that the runner is online and has every runs-on label. This workflow requires a persistent self-hosted Linux runner.