A Go implementation of the Imposter Mock Engine. This project is now considered stable.

• 💻 Run locally: Lightweight local HTTP mock server
• 🚀 Run in AWS Lambda: low latency, high throughput, <140ms cold start (see test results)
• ✅ REST/HTTP API mock support
• ✅ SOAP/WSDL mock support
• ✅ OpenAPI/Swagger mock support
• ✅ gRPC/Protobuf mock support (see examples/grpc)
• ✅ JavaScript scripting
• ✅ Support for steps
• ✅ Support for simulated delays, simulated errors and rate limiting

• No support for Groovy scripting

The recommended way to get started for most users is to use the latest Imposter CLI.

Note If you don't have Imposter CLI installed, or you want to use the imposter-go binary directly, continue to the Installation section.

With Imposter CLI installed, use the -t golang option, and pass -v <version>:

imposter up -t golang -v <version>

...where version is from the Releases page, for example:

imposter up -t golang -v 0.15.0

Download the latest release for your platform from GitHub:

# For Intel Macs (amd64)
curl -L https://github.com/imposter-project/imposter-go/releases/latest/download/imposter-go_darwin_amd64.tar.gz | tar xz
sudo mv imposter-go /usr/local/bin/

# For Apple Silicon Macs (arm64)
curl -L https://github.com/imposter-project/imposter-go/releases/latest/download/imposter-go_darwin_arm64.tar.gz | tar xz
sudo mv imposter-go /usr/local/bin/

# For amd64 systems
curl -L https://github.com/imposter-project/imposter-go/releases/latest/download/imposter-go_linux_amd64.tar.gz | tar xz
sudo mv imposter-go /usr/local/bin/

# For arm64 systems
curl -L https://github.com/imposter-project/imposter-go/releases/latest/download/imposter-go_linux_arm64.tar.gz | tar xz
sudo mv imposter-go /usr/local/bin/

1. Download the latest release from GitHub Releases
2. Extract the imposter-go_windows_amd64.zip file
3. Add the extracted imposter-go.exe to your PATH or move it to a directory in your PATH

Docker images are available on Docker Hub.

There are two image variants:

Each image is published with the following tags:

• 5-beta - latest beta release (major version)
• <version>-beta - specific version, e.g. 5.14.3-beta

docker run --rm -p 8080:8080 \
  -v /path/to/config:/opt/imposter/config \
  outofcoffee/imposter:5-beta

docker run --rm -p 8080:8080 \
  -v /path/to/config:/opt/imposter/config \
  outofcoffee/imposter:5.14.3-beta

To use the all-in-one image (with all plugins):

docker run --rm -p 8080:8080 \
  -v /path/to/config:/opt/imposter/config \
  outofcoffee/imposter-all:5-beta

Run with a directory containing Imposter configuration file(s):

imposter-go ./examples/rest/simple

Visit http://localhost:8080/hello in your browser or use curl:

curl http://localhost:8080/hello

The repository includes several examples demonstrating different features:

• Simple REST API - Basic REST API mocking
• SOAP Web Service - SOAP/WSDL-based service mocking
• OpenAPI HTTP API - OpenAPI-based service mocking
• AWS Lambda - Running Imposter in AWS Lambda

A subset of the Imposter environment variables are supported. For example:

Set the IMPOSTER_PORT environment variable to change the default port:

export IMPOSTER_PORT=9090  # Default: 8080

Enable recursive directory scanning for configuration files:

export IMPOSTER_CONFIG_SCAN_RECURSIVE=true  # Default: false

Set the IMPOSTER_SERVER_URL environment variable to override the URL reported by the server:

export IMPOSTER_SERVER_URL=http://example.com  # Default: http://localhost:8080

Set the IMPOSTER_LOG_LEVEL environment variable to control logging verbosity:

export IMPOSTER_LOG_LEVEL=DEBUG  # Available levels: TRACE, DEBUG, INFO, WARN, ERROR

The default log level is DEBUG. Available log levels:

• TRACE - Most verbose, logs all messages
• DEBUG - Detailed information for debugging
• INFO - General operational messages
• WARN - Warning messages for potentially harmful situations
• ERROR - Error messages for serious problems

By default Imposter serves HTTP/2. Without TLS the server runs with h2c (HTTP/2 cleartext), which also remains compatible with HTTP/1.1 clients.

To enable TLS (h2 — HTTP/2 over TLS), set both of:

export IMPOSTER_TLS_CERT_FILE=/path/to/server.crt
export IMPOSTER_TLS_KEY_FILE=/path/to/server.key

Both variables must be set; setting only one is ignored with a warning. When TLS is enabled, the default IMPOSTER_SERVER_URL scheme becomes https.

HTTP/2 can be disabled (serving HTTP/1.1 only) by setting IMPOSTER_HTTP2_ENABLED=false. This applies to both cleartext and TLS modes.

Imposter Go supports legacy configuration formats, for backwards compatibility with older Imposter configurations.

Enable support for legacy configuration format:

export IMPOSTER_SUPPORT_LEGACY_CONFIG=true

When legacy configuration support is enabled, older configuration formats are automatically transformed. For example:

# Legacy format (root-level fields)
plugin: rest
path: /hello
contentType: text/plain
response:
  staticData: Hello, World!

# Legacy format (deprecated names for resource-level fields)
plugin: rest
resources:
  - path: /hello
    contentType: application/json
    response:
      staticFile: response.json # Deprecated, use file instead
      staticData: Hello, World! # Deprecated, use content instead
      scriptFile: transform.js  # Deprecated, use a script step instead

See the Development Guide for instructions on building, testing, and contributing to the project.