How to Use ScreenshotMachine with Docker
ScreenshotMachine documents an HTTP screenshot API, not an official CLI or Docker image. Build a small Docker wrapper with curl, pass your API key at runtime, and save captures to a mounted folder.
ScreenshotMachine’s documented capture method is an HTTP GET API. The official materials reviewed for this guide do not document a vendor-maintained ScreenshotMachine CLI or Docker image. You can still run a command-line capture from Docker: use a small container with curl, call the API, and write the response into a host directory mounted at /output. This is a general Docker wrapper around the API, not an official ScreenshotMachine CLI recipe.
Be careful with similarly named tools: the Docker Hub image screenshotone/cli is for ScreenshotOne, a different service. This guide uses ScreenshotMachine’s API.
1. What you need
- Docker installed and available to your user.
- A ScreenshotMachine account and API key.
- A URL you are authorized to capture.
- A local directory to hold the resulting screenshot.
ScreenshotMachine documents its API endpoint as https://api.screenshotmachine.com/, with requests made using HTTP GET and query parameters. The API key is required; URL and image dimensions are among the documented parameters. Check the current ScreenshotMachine API reference for the exact parameter names, available formats, limits, and account requirements before using this wrapper.
2. Run a one-off capture with curl in Docker
This approach needs no local ScreenshotMachine CLI installation. Docker runs a curl image, while a bind mount makes the output available on your host.
Set the key and output directory
export SCREENSHOTMACHINE_API_KEY='YOUR_API_KEY'
mkdir -p ./screenshotsDo not put a real key in a Dockerfile, a committed script, or shell history shared with other users. For shared environments, use your platform’s secret mechanism. The example uses an environment variable for convenience.
Call the API and save the image
docker run --rm \
--mount "type=bind,source=$(pwd)/screenshots,target=/output" \
--env SCREENSHOTMACHINE_API_KEY \
curlimages/curl:latest \
--fail --show-error --silent --location \
--get 'https://api.screenshotmachine.com/' \
--data-urlencode "key=$SCREENSHOTMACHINE_API_KEY" \
--data-urlencode 'url=https://example.com' \
--data-urlencode 'dimension=1024x768' \
--output /output/example.pngReplace the example target URL and confirm parameter spelling and supported dimension syntax in the current API reference. The API key parameter shown in this illustrative curl wrapper should also be checked against your account’s current instructions before publishing or deploying it.
The host directory ./screenshots appears inside the container as /output; Docker’s bind mount makes example.png available on the host. The --rm flag removes the short-lived container after curl exits. Docker documents both container execution and bind mounts in its container run guide and bind mount guide.
3. Make the workflow repeatable
For repeated use, put the curl command in a script and build a small image. This remains your own wrapper; it does not turn it into a ScreenshotMachine-supported CLI.
Dockerfile
FROM curlimages/curl:latest
COPY capture.sh /usr/local/bin/capture
ENTRYPOINT ["/usr/local/bin/capture"]capture.sh
#!/bin/sh
set -eu
: "${SCREENSHOTMACHINE_API_KEY:?Set SCREENSHOTMACHINE_API_KEY}"
: "${TARGET_URL:?Set TARGET_URL}"
output_path="${OUTPUT_PATH:-/output/page.png}"
mkdir -p "$(dirname "$output_path")"
curl --fail --show-error --silent --location \
--get 'https://api.screenshotmachine.com/' \
--data-urlencode "key=$SCREENSHOTMACHINE_API_KEY" \
--data-urlencode "url=$TARGET_URL" \
--data-urlencode "dimension=${DIMENSION:-1024x768}" \
--output "$output_path"
printf 'Saved screenshot to %s\n' "$output_path"Make the script executable and build the image:
chmod +x capture.sh
docker build -t my-screenshotmachine-wrapper .Run it with the output directory mounted:
docker run --rm \
--mount "type=bind,source=$(pwd)/screenshots,target=/output" \
--env SCREENSHOTMACHINE_API_KEY \
--env TARGET_URL='https://example.com' \
--env DIMENSION='1024x768' \
my-screenshotmachine-wrapperFor production, pin the curl image to a reviewed version or digest rather than relying indefinitely on latest. Validate the target URL if other users can supply it; otherwise the wrapper may be misused to make requests to destinations you did not intend.
4. Use a language client inside Docker
If your application is already written in a supported language, run its API client in a language runtime container. ScreenshotMachine publishes API samples, including Bash and Node.js; its published examples are the right place to confirm request construction and optional parameters. The same key-handling rule applies: inject credentials at runtime.
For example, a Node.js container can execute your own script that builds the documented API URL and downloads the response. The precise query fields and response handling should follow the current API documentation and ScreenshotMachine code samples; do not assume a Docker image or executable is provided by ScreenshotMachine.
5. Configure output and request options
| Need | Where to configure it | What to verify |
|---|---|---|
| Target page | API URL query parameter | Use a fully qualified URL and URL-encode it. |
| Image dimensions | API dimension parameter | Confirm accepted dimension format and account limits. |
| Output location | --output /output/name.png |
Ensure /output is mounted and writable. |
| Credentials | Runtime environment variable or container secret | Never copy the key into the image or source control. |
Other capture controls may be available in ScreenshotMachine’s current API reference. Add only documented parameters, encode values using --data-urlencode, and choose a file extension that matches the response format requested. Avoid assuming a parameter name from another screenshot service.
6. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Authentication or invalid-key response | The key is unset, incorrect, or passed using the wrong parameter name. | Confirm the variable is present in the container and check the current API reference for authentication syntax. Avoid printing the key in logs. |
| Bad request or parameter error | A query field or value is misspelled or unsupported. | Compare each parameter with ScreenshotMachine’s current API documentation. URL-encode the target and other values. |
| The output file is missing on the host | The bind mount source is wrong, relative to an unexpected directory, or not writable. | Use an absolute host path and confirm the container writes under the mounted destination, such as /output. |
| The saved file contains an error page or is not an image | The API returned an error response, or the response format did not match the chosen filename. | Keep curl’s --fail option, inspect the response and API status, and align the requested output format with the file extension. |
| Container exits with a curl error | DNS, TLS, network access, or a remote timeout failed. | Check Docker network access, retry transient failures with bounded retries, and inspect curl’s exit status. Do not retry indefinitely. |
| Permission denied writing output | The mounted host directory permissions prevent the container user from writing. | Choose a writable directory and adjust its ownership or permissions for the runtime user. |
| A page looks incomplete | The page may load content asynchronously or restrict automated access. | Consult documented capture options and account behavior. A command-line download cannot itself guarantee that all dynamic page content has rendered. |
7. Performance, reliability, and cost
Docker adds a container startup step, but the remote capture request and page rendering are generally the work the workflow must wait for. Reuse a container for batches instead of starting one per URL when startup overhead matters. Keep timeouts bounded, log the target and result status without logging credentials, and retry only transient failures with a small limit and backoff.
For dependable automation, check the API response before treating a file as a valid screenshot, write to a temporary path before renaming it into place, and make retries safe so a failed run does not leave a misleading partial artifact. Confirm ScreenshotMachine’s current account pricing, usage limits, and behavior for failed requests directly in its documentation or account interface; this research does not establish those details.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. It returns an image or PDF from one GET request; see the API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpCookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for 1,000 free screenshots a month.
FAQ
Is there an official ScreenshotMachine CLI command?
The official materials reviewed for this guide document an HTTP API and code samples, but do not document an official CLI command. Verify current product documentation before relying on a third-party wrapper.
Is screenshotone/cli the right Docker image?
No. It is described as a CLI for ScreenshotOne, a separate screenshot service.
Does Docker make the capture run locally?
No. Docker runs the curl command or client locally; the screenshot capture is requested from ScreenshotMachine’s API.
Can I use the downloaded image in a CI job?
Yes. Mount a workspace output directory and pass the key through your CI secret store. Confirm the API account’s usage limits and do not expose the key in build logs.
