DOCSEARCHbyAlgolia
Submit Docs

Speedscale Documentation

website·Indexed 34 days ago

https://docs.speedscale.com

Guides for installing and configuring Speedscale, including the speedctl and proxymock CLIs, the Speedscale Operator Helm chart, and methods for improving mock match rates using replay reports.

Tokens
3.2K
Snippets
16
Records
21
Agent score
16%

What's inside Speedscale

  1. Overview of Speedscale Components

    Speedscale consists of three primary components depending on the user's needs:

    • speedctl: A CLI for the Speedscale cloud used to pull/push snapshots, run replays, and manage clusters. Required for operator verification.
    • proxymock: A local record, mock, and replay CLI featuring a built-in MCP server and web UI. Intended for developer laptops and AI-agent integration.
    • Speedscale Operator: A Helm chart (speedscale/speedscale-operator) used to capture traffic in Kubernetes and run in-cluster replays.

  2. Install Speedscale CLIs via Official Scripts

    For macOS, Linux, or WSL (without Homebrew), use the official installation scripts. These scripts download the correct architecture, verify the SHA-256 checksum, and place binaries in ~/.speedscale/ without requiring root privileges. To pin a specific version, append -s vX.Y.Z to the script command.
    sh -c "$(curl -Lfs https://downloads.speedscale.com/speedctl/install)"
sh -c "$(curl -Lfs https://downloads.speedscale.com/proxymock/install-proxymock)"

  3. Speedscale Installation Ground Rules

    When installing or managing Speedscale, adhere to these constraints:

    • Avoid speedctl install: This is an interactive TUI wizard; use Helm directly for cluster installations to maintain visibility of configuration values.
    • API Key Security: Never print or log API keys. Store them in ~/.speedscale/config.json or the SPEEDSCALE_API_KEY environment variable. Pass them by reference.
    • User-space First: Install binaries under $HOME to avoid using sudo unless absolutely necessary.
    • Idempotency: Use helm upgrade --install instead of helm install to ensure the process is idempotent.
    • Cluster Safety: Always verify the current kube-context before modifying a cluster. Avoid installing on production clusters (prod, prd, live) without explicit confirmation.

  4. Improve Speedscale mock match rate using the tuning loop

    To improve the outbound mock match rate (the fraction of outbound requests answered by recorded mocks), use an iterative offline loop within a local workspace. The goal is to increase the Projected Match Rate (what the next replay would score) by applying transforms to the workspace's tuning blueprint.

    The Tuning Loop:

    1. Locate Workspace: Run mocks action=analyze on the local directory. If no mock/request source is found, use pull_report with a report ID to fetch the report and source snapshot into a workspace, then run analyze.
    2. Baseline: Note the report and projected match rates. Stop if the projected rate is 100%.
    3. Triage: Review recommendation groups and drift summaries. Use mocks action=similar to inspect per-field causes for ambiguous misses.
    4. Apply: Use mocks action=accept for high-confidence fixes, starting with the largest groups.
    5. Verify: Ensure the projected rate does not drop. If it does, use mocks action=undo.
    6. Iterate: Repeat until the projected rate is 100%, no recommendations remain, or no improvement is seen for two rounds (cap at ~8 rounds).
    7. Report: Summarize before/after rates and accepted fixes. Recommend a confirming replay and use snapshot action=push to sync the blueprint to the cloud.

  6. Install Speedscale Prerequisites

    Depending on the operating system and installation mode (local vs cluster), the following prerequisites may be required. Ensure the installation directory is added to the user's PATH (e.g., in ~/.zshrc or ~/.bashrc).
    # macOS
brew install kubectl
brew install helm

# Linux (User-space)
# kubectl: official binary to ~/.local/bin
# helm: get-helm-3 script with HELM_INSTALL_DIR=$HOME/.local/bin

# Windows
winget install Kubernetes.kubectl
winget install Helm.Helm

  7. Verify the Speedscale cluster installation

    After installation, verify the health of the cluster using the bundled verification script. A successful installation is confirmed when:

    1. The Helm release status is deployed.
    2. Operator, forwarder, and inspector Deployments are Available.
    3. speedctl check operator -n speedscale reports success.
    4. The cluster appears in speedctl infra inspectors and the Speedscale dashboard.
    5. If eBPF is enabled, the speedscale-nettap DaemonSet is READY.
    sh scripts/verify.sh speedscale

  8. Securely store the Speedscale API key in Kubernetes

    To keep the API key out of Helm values, release history, and rendered manifests, store it in a Kubernetes Secret. Use the scripts/apikey.sh utility to dynamically retrieve the key and the appropriate application URL for the current context.
    kubectl create namespace speedscale --dry-run=client -o yaml | kubectl apply -f -
kubectl -n speedscale create secret generic speedscale-apikey \
  --from-literal=SPEEDSCALE_API_KEY="$(sh scripts/apikey.sh)" \
  --from-literal=SPEEDSCALE_APP_URL="$(sh scripts/apikey.sh --app-url)" \
  --dry-run=client -o yaml | kubectl apply -f -

  9. Install the Speedscale operator using Helm

    Install the Speedscale operator by adding the official Helm repository and applying the configuration from your values file. The installation includes pre-install hooks that validate the API key and connectivity. If the installation fails with BackoffLimitExceeded, check the logs of the speedscale-operator-pre-install job.
    helm repo add speedscale https://speedscale.github.io/operator-helm/
helm repo update speedscale
helm upgrade --install speedscale-operator speedscale/speedscale-operator \
  -n speedscale --create-namespace \
  -f speedscale-values.yaml \
  --wait --timeout 10m

# To debug pre-install failures:
kubectl -n speedscale logs job/speedscale-operator-pre-install

  11. Install the proxymock MCP server for coding agents

    The proxymock MCP server allows AI coding agents to perform record, mock, and replay operations locally and interact with the Speedscale operator. Use the mcp install command to configure detected IDE clients. For non-detected IDEs, use mcp json to get the configuration block. If the IDE cannot spawn the process directly, use --http to serve the MCP server via Streamable HTTP.
    # Install into all detected clients
proxymock mcp install --yes

# For remote dev boxes/containers (HTTP mode)
proxymock mcp run --http
proxymock mcp install --http

  12. Authenticate Speedscale CLIs

    Both speedctl and proxymock share a single configuration file located at ~/.speedscale/config.json. Authentication can be performed in two ways:

    1. Interactive: Run proxymock init or speedctl init in a terminal to open a browser-based sign-in flow.
    2. Non-Interactive (API Key): If an API key is available via the SPEEDSCALE_API_KEY environment variable, use the --api-key flag with the -y (yes) flag to bypass prompts. Note: Non-interactive initialization requires proxymock Pro or Speedscale Enterprise.
    speedctl init --api-key "$SPEEDSCALE_API_KEY" -y