How to Set Up the Apidog Self-Hosted Runner for Scheduled API Tests

Your API test suite is only useful if it runs on a schedule you can trust. A collection you trigger by hand catches bugs when you remember to click. A nightly run on a machine you control catches them at 2 a.m., before your users do. That’s the job of the Apidog runner: a self-deployed service, installed with Docker on your own server, which executes the scheduled test scenarios you build in Apidog and pushes the reports back into your project.

We’ve covered the three ways to schedule tests in Apidog in our guide to scheduling automated API tests. That post compares cloud execution, the runner, and the CLI at a high level. This one is the deep dive on the runner path: when you need it, how to deploy it, how to point a scheduled task at it, and how it compares to the alternatives.

When you need a self-hosted test runner

Cloud execution is convenient, but three situations push teams toward a self hosted test runner.

Your APIs live on a private network. A staging environment at https://orders.staging.internal:8443 doesn’t resolve from the public internet. No cloud service can reach it. A runner deployed inside your VPC or office network can, because it makes requests from where it sits. This is the same reasoning behind running a self-hosted mock server on your intranet: the workload has to live where the network access is.

Compliance keeps traffic in-house. If your security team prohibits test payloads with realistic customer data from leaving your infrastructure, cloud execution is off the table. With the runner, requests originate from your server and hit your APIs directly. Only the test reports travel back to Apidog.

You want stable schedules independent of any laptop. Tests scheduled inside the desktop app stop when the app closes. Tests wired into CI run when someone pushes code. Neither gives you “every 6 hours, forever, no matter what.” A runner on an always-on server does exactly this.

If none of these apply, you probably don’t need a runner. Manual runs in the app or the CLI in CI will cover you.

What the Apidog runner is

The self-hosted runner is an automation service you deploy on an independent server. Once connected to your team, it can:

• Run scheduled automated test tasks built from your Apidog test scenarios
• Import API documentation on a recurring schedule
• Serve self-hosted mock responses

It comes in two scopes. A team-level general runner belongs to one team. An organization-level runner can be shared across all projects in your organization’s teams. Deployment works the same way for both.

The key mental model: the runner is a worker, not a copy of your project. Your test scenarios, environments, and assertions stay in Apidog. The runner receives tasks, executes them against whatever network it can reach, and uploads the results. Team members never SSH into it to see what happened; they open the run history in the app.

Prerequisites

Check these before you deploy. They come straight from the runner deployment environment docs.

Hardware. Minimum 2 CPU cores and 4 GB of RAM; 4+ cores and 8 GB are recommended if you’ll run concurrent tasks or have a larger team. Budget at least 30 GB of disk for logs and test artifacts, 50 GB to be comfortable.

Docker. The host needs Docker version 20.10.0 or later, with 20.10.13 recommended. If the server is fresh, follow the official Docker Engine install guide for your distribution first.

Network. The runner talks to the Apidog server over HTTPS on port 443 and keeps a WebSocket (WSS) connection open for real-time task dispatch. It also needs outbound access to the AWS domains used for report uploads, plus, obviously, network reach to every API your tests target. Note the direction here: the runner dials out. You don’t need to open inbound ports for Apidog to reach it, which makes firewall conversations with your ops team short.

Permissions and plan. Deploying a runner is a team resource action, so you’ll need the appropriate team role. How many scheduled task runs you get depends on your subscription tier; check the Apidog pricing page for current limits per plan.

Step 1: get the deployment command from Apidog

Apidog generates the Docker deployment command for you, with an auth token baked in. Don’t copy one from a blog post, including this one; the token is what binds the container to your team.

1. Open Apidog and go to the Apidog Home page. If you don’t have an account yet, download Apidog free to follow along.
2. Select the team the runner should belong to.
3. Click Resources on the right side.
4. Click Deploy General Runner.

A popup shows the full deployment command. Copy it immediately: it contains a sensitive token and is displayed only once. Treat it like a CI secret, not a snippet for your team wiki.

Before copying, the dialog lets you tailor the command:

• Server OS: Linux, macOS, or Windows.
• Image variant: General ships with Node.js 18, Java 21, Python 3, and PHP 8, so pre/post-processor scripts in those languages work without extra setup. Slim includes only Node.js 18 and pulls faster. Custom lets you supply your own Dockerfile when tests depend on internal CA certificates or unusual libraries.
• Exposed port: map one with -p (for example -p 80:4524) if you’ll also use the runner for self-hosted mocks.
• Mounted data directory: add a -v volume mount if your test scenarios read local data files, such as CSV datasets for data-driven runs.

The general runner docs cover each option in detail.

Step 2: run the container and confirm it’s connected

SSH into the target server, paste the command, and let Docker pull the image and start the container. Two operational notes worth setting on day one:

• Pass TZ as an environment variable (for example TZ=Asia/Singapore) so “every day at 02:00” means your 02:00, not the container default.
• From runner version 2.2.5, the image includes a non-root runner user (UID/GID 10001). If your platform enforces runAsNonRoot, set the security context accordingly and pre-configure volume permissions, since the entrypoint can’t chown directories in non-root mode.

Back in Apidog, the runner appears under your team’s Resources once the WebSocket handshake completes, and team members can select it when creating tasks. If it doesn’t show up within a minute, check the container logs with docker logs and confirm the host can reach the Apidog server on port 443; a blocked WSS connection is the usual culprit on locked-down corporate networks.

You can deploy several runners in one team. Teams often keep one inside the staging VPC and another with production read access, then pick per task.

Step 3: create a scheduled task targeting the runner

With the runner online, scheduling is a form, not a script.

1. In your project, open the Tests module and click Scheduled Tasks. Tasks live in a folder structure, so group them by service or environment as the list grows.
2. Create a task and give it a name a teammate will understand in six months: “Orders service smoke, staging, every 6h” beats “test1”.
3. Select one or more test scenarios. Per scenario you can set the environment, test data, iteration count, delay between requests, and whether to save request/response bodies.
4. Set the environment and variable scope. Applying variables to all scenarios within the task is the recommended middle ground; folder-wide scope is powerful but easy to trip over.
5. Set the Run Cycle: every Sunday at 11 p.m., every 6 hours, whatever matches how quickly you need to know something broke.
6. Under Runs on, pick your self-hosted runner by name.
7. Configure notifications. You can alert after every run or only on failure. Failure-only is the sane default; a channel full of green checkmarks trains everyone to ignore it.

Save it. From this point the schedule executes on your server whether or not anyone has the Apidog app open.

Step 4: read the run reports in Apidog

After each run, the runner uploads results to the Apidog server automatically. Open Scheduled Tasks → Run History in the app to see every execution: pass/fail status, per-scenario results, assertion failures, and timing.

This is the quiet advantage of the runner over a homegrown cron-plus-scripts setup. The execution happens on your infrastructure, but the reporting lands in the same shared workspace where the tests are defined. When Tuesday’s 02:00 run fails, the QA engineer who investigates sees which assertion failed on which step, in context, without grepping a server for log files.

Pair the failure notifications with the run history and you have a monitoring loop: alert fires, open the report, reproduce the failing step manually in the app against the same environment, fix, and wait for the next green run.

Runner vs CLI vs cloud: choosing an execution path

Apidog gives you three ways to execute tests beyond a manual click in the app, and they solve different problems. We’ve written a full walkthrough of the CI path in our Apidog CLI GitHub Actions guide, and the comparison below shows where each fits.

The paths compose rather than compete. A common setup: the CLI gates every deploy in the pipeline, while the runner executes an hourly smoke suite against staging and a nightly full regression, catching the failures caused by infrastructure drift and expiring credentials rather than code changes.

One caveat on timing: per the scheduled tasks docs, scheduled tasks are designed to run on a self-hosted runner, with Apidog Cloud selectable as availability rolls out. If you need scheduled execution today and can’t wait on cloud availability for your plan, the runner is the dependable route.

FAQ

Do I need the runner if I already use Apidog CLI in CI?

They answer different questions. CI tells you “did this change break the API?” at push time. The runner tells you “is the API healthy right now?” on a fixed cycle, catching failures caused by expired tokens, dead dependencies, or infrastructure drift with no commit attached. Many teams run both; see our nightly API test setup guide for the CI-scheduled half of the pattern.

Can the runner reach intranet APIs?

Yes, and this is its main reason to exist. The runner makes requests from the machine it’s deployed on. Put it inside your VPC or office network and it can test *.internal hosts no cloud service can resolve. It only needs outbound HTTPS and WebSocket access to the Apidog server to receive tasks and upload reports.

What are the minimum server specs?

Two CPU cores, 4 GB of RAM, 30 GB of disk, and Docker 20.10.0 or later. For teams running concurrent scheduled tasks, move to 4+ cores and 8 GB. A small VM or a spare box in the office rack both work; the constraint is uptime, not horsepower.

Which plan do I need for scheduled tasks on a self-hosted runner?

Scheduled task run quotas vary by subscription tier, so check the current limits on the Apidog pricing page before you plan a high-frequency schedule. If you’re evaluating execution options across tools, our Apidog CLI vs Postman CLI comparison looks at what the test-runner side of each platform includes.