Browse documentation
Guides
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.
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 — 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"
}On a Linux Docker host with curl, tar and sha256sum, download the pinned CLI for the host CPU. Save image/Dockerfile and image/.dockerignore below, build the image, then save runtime.sh. The helper runs as your UID/GID and mounts the state and task folders into each new container.
(
set -euo pipefail
case "$(uname -m)" in
x86_64) arch=amd64 ;;
aarch64|arm64) arch=arm64 ;;
*) echo 'Use a Linux amd64 or arm64 host.' >&2; exit 1 ;;
esac
mkdir -p image
cd image
archive="flashdata_1.2.1_linux_$arch.tar.gz"
base='https://github.com/flashdatadev/flashdata-cli/releases/download/v1.2.1'
curl --fail --show-error --location "$base/$archive" -o "$archive"
curl --fail --show-error --location "$base/SHA256SUMS" -o SHA256SUMS
awk -v file="$archive" '$2 == file { print }' SHA256SUMS | sha256sum -c -
tar -xzf "$archive" flashdata
)FROM debian:bookworm-slim
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY --chmod=0755 flashdata /usr/local/bin/flashdata
USER 10001:10001
ENTRYPOINT ["/usr/local/bin/flashdata"]*
!Dockerfile
!flashdatadocker build --tag flashdata-runtime:1.2.1 ./image
docker run --rm flashdata-runtime:1.2.1 --version# runtime.sh — use the local image built above.
export FLASHDATA_IMAGE='flashdata-runtime:1.2.1'
export FLASHDATA_PROFILE=research
export FLASHDATA_STATE_DIR="$HOME/.local/state/flashdata-research"
run_flashdata() {
docker run --rm -i --user "$(id -u):$(id -g)" \
--env FLASHDATA_API_KEY= \
--mount "type=bind,src=$FLASHDATA_STATE_DIR,dst=/state" \
--mount "type=bind,src=$PWD,dst=/work" --workdir /work \
--entrypoint /usr/local/bin/flashdata "$FLASHDATA_IMAGE" \
"$@" --profile "$FLASHDATA_PROFILE" --state-dir /state
}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.
set -euo pipefail
umask 077
. ./runtime.sh
mkdir -p "$FLASHDATA_STATE_DIR"
chmod 700 "$FLASHDATA_STATE_DIR"
run_flashdata --version
jq --version2. 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.
export FLASHDATA_KEY_FILE='/run/secrets/flashdata_api_key'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-interactiveConfirm 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.
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.jsonCredential 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.
| Keep | Location |
|---|---|
| Credentials and run journal | FLASHDATA_STATE_DIR |
| Input, receipts and results | The 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.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
}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.json4. 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.
#!/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.
# 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.shVerify 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.
{
"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.
# 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.
- Assign the flashdata-research label to that runner.
- Set repository variables FLASHDATA_BIN and FLASHDATA_STATE_DIR to its absolute paths, and FLASHDATA_PROFILE to the installed profile name.
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.
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-interactiveStop 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
| Symptom | Fix |
|---|---|
| Command not found / wrong CLI version | Check command -v flashdata and FLASHDATA_BIN in runtime.sh. For Docker, rebuild and run the image's --version check. |
| Missing mount or permission denied | Create the state and task folders on the Docker host, owned by the service UID/GID. Keep their paths stable. |
| replacement_requires_flag | The profile has a different saved key. Verify existing access first; use the rotation procedure for an intended replacement. |
| Cannot decrypt saved access | Run 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 false | Inspect balance.json and preflight.json. Require an available price, source permission and enough balance before submitting. |
| run_account_mismatch | Check the selected account and API origins. Restore the original access; do not rename the run to bypass recovery. |
| run_id_input_conflict | Restore the original request from the attempt's request.json. Use a new run ID only for an intended new paid task. |
| CI stays queued | Check that the runner is online and has every runs-on label. This workflow requires a persistent self-hosted Linux runner. |