Wait4X is a lightweight, zero-dependency tool to wait for services to be ready. Perfect for CI/CD, containers, and local development.
Wait4X helps you wait for services (databases, APIs, message queues, etc.) to be ready before your app or script continues. It's ideal for:
| Feature | Description |
|---|---|
| Multi-Protocol | TCP, HTTP, DNS, and more |
| Service Integrations | Redis, MySQL, PostgreSQL, MongoDB, Kafka, RabbitMQ, InfluxDB, Temporal |
| Reverse/Parallel Checking | Invert checks or check multiple services at once |
| Exponential Backoff | Smarter retries |
| Cross-Platform | Single binary for Linux, macOS, Windows |
| Go Package | Use as a Go library |
| Command Execution | Run commands after checks |
After installing, jump to Quick Start to try it out!
Wait4X provides automatically updated Docker images within Docker Hub:
# Pull the image
docker pull wait4x/wait4x:latest
# Run the container
docker run --rm wait4x/wait4x:latest --help
macOS:
brew install wait4x
Alpine Linux:
apk add wait4x
Arch Linux (AUR):
yay -S wait4x-bin
NixOS:
nix-env -iA nixpkgs.wait4x
Windows (Scoop):
scoop install wait4x
Download the appropriate version for your platform from the releases page:
Linux:
curl -LO https://github.com/wait4x/wait4x/releases/latest/download/wait4x-linux-amd64.tar.gz
tar -xf wait4x-linux-amd64.tar.gz -C /tmp
sudo mv /tmp/wait4x-linux-amd64/wait4x /usr/local/bin/
macOS:
curl -LO https://github.com/wait4x/wait4x/releases/latest/download/wait4x-darwin-amd64.tar.gz
tar -xf wait4x-darwin-amd64.tar.gz -C /tmp
sudo mv /tmp/wait4x-darwin-amd64/wait4x /usr/local/bin/
Windows:
curl -LO https://github.com/wait4x/wait4x/releases/latest/download/wait4x-windows-amd64.tar.gz
tar -xf wait4x-windows-amd64.tar.gz
# Move to a directory in your PATH
Verify checksums:
curl -LO https://github.com/wait4x/wait4x/releases/latest/download/wait4x-linux-amd64.tar.gz.sha256sum
sha256sum --check wait4x-linux-amd64.tar.gz.sha256sum
You can install Wait4X directly from source using Go (requires Go 1.16+):
go install wait4x.dev/v3/cmd/wait4x@latest
This will place the wait4x binary in your $GOPATH/bin or $HOME/go/bin directory.
Get started in seconds! After installing, try these common checks:
wait4x tcp localhost:3306
wait4x http https://example.com/health --expect-status-code 200
wait4x tcp 127.0.0.1:5432 127.0.0.1:6379 127.0.0.1:27017
wait4x postgresql 'postgres://user:pass@localhost:5432/mydb?sslmode=disable'
For more, see Usage Examples or Detailed Usage.
Here are some of the most useful Wait4X commands. Click the links for more details!
wait4x tcp localhost:8080wait4x http https://api.example.com/health --expect-status-code 200 --expect-body-regex '"status":"UP"'wait4x dns A example.comwait4x mysql 'user:password@tcp(localhost:3306)/mydb'wait4x redis redis://localhost:6379 --expect-key "session:active"wait4x tcp localhost:8080 -- ./start-app.shwait4x tcp localhost:8080 --invert-checkwait4x tcp localhost:3306 localhost:6379 localhost:27017See Detailed Usage for advanced options and more protocols.
Jump to:
Wait for an HTTP(S) endpoint to be ready, with flexible validation options.
wait4x http https://api.example.com/health --expect-status-code 200
wait4x http https://api.example.com/status --expect-body-regex '"status":\s*"healthy"'
wait4x http https://api.example.com/status --expect-body-json "services.database.status"
wait4x http https://example.com --expect-body-xpath "//div[@id='status']"
wait4x http https://api.example.com \
--request-header "Authorization: Bearer token123" \
--request-header "Content-Type: application/json"
wait4x http https://api.example.com --expect-header "Content-Type=application/json"
wait4x http https://www.wait4x.dev --cert-file /path/to/certfile --key-file /path/to/keyfile
wait4x http https://www.wait4x.dev --ca-file /path/to/cafile
Check for various DNS record types and values.
wait4x dns A example.com
wait4x dns A example.com --expected-ip 93.184.216.34
wait4x dns A example.com --expected-ip 93.184.216.34 -n 8.8.8.8
wait4x dns AAAA example.com --expected-ip "2606:2800:220:1:248:1893:25c8:1946"
wait4x dns CNAME www.example.com --expected-domain example.com
wait4x dns MX example.com --expected-domain "mail.example.com"
wait4x dns NS example.com --expected-nameserver "ns1.example.com"
wait4x dns TXT example.com --expected-value "v=spf1 include:_spf.example.com ~all"
Check readiness for popular databases.
wait4x mysql 'user:password@tcp(localhost:3306)/mydb'
wait4x mysql 'user:password@unix(/var/run/mysqld/mysqld.sock)/mydb'
wait4x mysql 'user:password@tcp(localhost:3306)/mydb' --expect-table my_table
wait4x postgresql 'postgres://user:password@localhost:5432/mydb?sslmode=disable'
wait4x postgresql 'postgres://user:password@/mydb?host=/var/run/postgresql'
wait4x postgresql 'postgres://user:password@localhost:5432/mydb?sslmode=disable' --expect-table my_table
currentSchema=myschema connection string parameter, for example:
wait4x postgresql 'postgres://user:password@localhost:5432/mydb?sslmode=disable¤tSchema=myschema' --expect-table my_table
wait4x mongodb 'mongodb://user:password@localhost:27017/mydb?maxPoolSize=20'
wait4x redis redis://localhost:6379
wait4x redis redis://user:password@localhost:6379/0
wait4x redis redis://localhost:6379 --expect-key "session:active"
wait4x redis redis://localhost:6379 --expect-key "status=^ready$"
wait4x influxdb http://localhost:8086
wait4x rabbitmq 'amqp://guest:guest@localhost:5672/myvhost'
wait4x temporal server localhost:7233
wait4x temporal worker localhost:7233 \
--namespace my-namespace \
--task-queue my-queue
wait4x temporal worker localhost:7233 \
--namespace my-namespace \
--task-queue my-queue \
--expect-worker-identity-regex "worker-.*"
Basic Kafka broker readiness check:
wait4x kafka kafka://localhost:9092
Check Kafka broker with SCRAM authentication:
wait4x kafka kafka://user:pass@localhost:9092?authMechanism=scram-sha-256
Wait for multiple Kafka brokers (cluster) to be ready:
wait4x kafka kafka://broker1:9092 kafka://broker2:9092 kafka://broker3:9092
Notes:
- The connection string format is: kafka://[user:pass@]host:port[?option=value&...]
- Supported options: authMechanism (scram-sha-256, scram-sha-512)
Wait for a shell command to succeed or return a specific exit code.
wait4x exec 'ping wait4x.dev -c 2'
wait4x exec 'ls target/debug/main' --exit-code 2
See Advanced Features for timeout, retry, backoff, and parallel/reverse checking options.
Jump to:
Control how long Wait4X waits and how often it checks.
Set a timeout:
wait4x tcp localhost:8080 --timeout 30s
Waits up to 30 seconds before giving up.
Set check interval:
wait4x tcp localhost:8080 --interval 2s
Checks every 2 seconds (default: 1s).
Retry with increasing delays for more efficient waiting (useful for slow-starting services).
wait4x http https://api.example.com \
--backoff-policy exponential \
--backoff-exponential-coefficient 2.0 \
--backoff-exponential-max-interval 30s
Wait for a service to become unavailable (e.g., port to be free, service to stop).
wait4x tcp localhost:8080 --invert-check
wait4x http https://service.local/health --expect-status-code 200 --invert-check
Run a command after a successful check (great for CI/CD or startup scripts).
wait4x tcp localhost:3306 -- ./deploy.sh
wait4x redis redis://localhost:6379 -- echo "Redis is ready" && ./init-redis.sh
Wait for multiple services at once (all must be ready to continue).
wait4x tcp localhost:3306 localhost:6379 localhost:27017
See CLI Reference for all available flags and options.
Add Wait4X to your Go project:
go get wait4x.dev/v3
Import the packages you need:
import (
"context"
"time"
"wait4x.dev/v3/checker/tcp" // TCP checker
"wait4x.dev/v3/checker/http" // HTTP checker
"wait4x.dev/v3/checker/redis" // Redis checker
"wait4x.dev/v3/waiter" // Waiter functionality
)
// Create a context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
// Create a TCP checker
tcpChecker := tcp.New("localhost:6379", tcp.WithTimeout(5*time.Second))
// Wait for the TCP port to be available
err := waiter.WaitContext(
ctx,
tcpChecker,
waiter.WithTimeout(time.Minute),
waiter.WithInterval(2*time.Second),
waiter.WithBackoffPolicy("exponential"),
)
if err != nil {
log.Fatalf("Failed to connect: %v", err)
}
fmt.Println("Service is ready!")
// Create HTTP headers
headers := http.Header{}
headers.Add("Authorization", "Bearer token123")
headers.Add("Content-Type", "application/json")
// Create an HTTP checker with validation
checker := http.New(
"https://api.example.com/health",
http.WithTimeout(5*time.Second),
http.WithExpectStatusCode(200),
http.WithExpectBodyJSON("status"),
http.WithExpectBodyRegex(`"healthy":\s*true`),
http.WithExpectHeader("Content-Type=application/json"),
http.WithRequestHeaders(headers),
)
// Wait for the API to be ready
err := waiter.WaitContext(ctx, checker, options...)
// Create checkers for multiple services
checkers := []checker.Checker{
redis.New("redis://localhost:6379"),
postgresql.New("postgres://user:pass@localhost:5432/db"),
http.New("http://localhost:8080/health"),
}
// Wait for all services in parallel
err := waiter.WaitParallelContext(
ctx,
checkers,
waiter.WithTimeout(time.Minute),
waiter.WithBackoffPolicy(waiter.BackoffPolicyExponential),
)
// Define your custom checker
type FileChecker struct {
filePath string
minSize int64
}
// Implement Checker interface
func (f *FileChecker) Identity() (string, error) {
return fmt.Sprintf("file(%s)", f.filePath), nil
}
func (f *FileChecker) Check(ctx context.Context) error {
// Check if context is done
select {
case <-ctx.Done():
return ctx.Err()
default:
// Continue checking
}
fileInfo, err := os.Stat(f.filePath)
if err != nil {
if os.IsNotExist(err) {
return checker.NewExpectedError(
"file does not exist",
err,
"path", f.filePath,
)
}
return err
}
if fileInfo.Size() < f.minSize {
return checker.NewExpectedError(
"file is smaller than expected",
nil,
"path", f.filePath,
"actual_size", fileInfo.Size(),
"expected_min_size", f.minSize,
)
}
return nil
}
For more detailed examples with complete code, see the examples/pkg directory. Each example is in its own directory with a runnable main.go file.
Wait4X provides a flexible CLI with many commands and options. Here is a summary of the main commands and global flags. For the most up-to-date and detailed information, use the built-in help:
wait4x --help
wait4x <command> --help
| Command | Description |
|---|---|
tcp | Wait for a TCP port to become available |
http | Wait for an HTTP(S) endpoint with advanced checks |
dns | Wait for DNS records (A, AAAA, CNAME, MX, etc.) |
kafka | Wait for Kafka server |
mysql | Wait for a MySQL database to be ready |
postgresql | Wait for a PostgreSQL database to be ready |
mongodb | Wait for a MongoDB database to be ready |
redis | Wait for a Redis server or key |
influxdb | Wait for an InfluxDB server |
rabbitmq | Wait for a RabbitMQ server |
temporal | Wait for a Temporal server or worker |
exec | Wait for a shell command to succeed |
Each command supports its own set of flags. See examples above or run wait4x <command> --help for details.
| Flag | Description |
|---|---|
--timeout, -t | Set the maximum wait time (e.g., 30s, 2m) |
--interval, -i | Set the interval between checks (default: 1s) |
--invert-check | Invert the check (wait for NOT ready) |
--backoff-policy | Retry policy: linear or exponential |
--backoff-exponential-coefficient | Exponential backoff multiplier (default: 2.0) |
--backoff-exponential-max-interval | Max interval for exponential backoff |
--quiet | Suppress output except errors |
--no-color | Disable colored output |
For a full list of commands and options, run:
wait4x --help
wait4x <command> --help
We welcome contributions of all kinds! Whether you want to fix a bug, add a feature, improve documentation, or help others, you're in the right place.
How to contribute:
git checkout -b feature/your-feature-namemake testgit commit -am 'Describe your change'git push origin feature/your-feature-nameFound a bug or have a feature request?
For more details, see CONTRIBUTING.md (if available).
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Copyright 2019-2025 The Wait4X Authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
The project logo is based on the "Waiting Man" character (Zhdun) and is used with attribution to the original creator.
FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Threat actors compromised four oorzc Open VSX extensions with more than 22,000 downloads, pushing malicious versions that install a staged loader, evade Russian-locale systems, pull C2 from Solana memos, and steal macOS credentials and wallets.
Security News
Lodash 4.17.23 marks a security reset, with maintainers rebuilding governance and infrastructure to support long-term, sustainable maintenance.
Security News
n8n led JavaScript Rising Stars 2025 by a wide margin, with workflow platforms seeing the largest growth across categories.