slim

repository·main·Indexed 23 days ago

A CLI tool for mapping local domains to local ports with automatic HTTPS support. Slim manages host file entries and SSL certificates, providing a background daemon for proxying and port forwarding. It supports custom TLDs, path-based routing via the --route flag, and project-wide configuration using .slim.yaml files. Additionally, it allows exposing local servers to the internet via public slim.show URLs and custom domains.

Tokens: 5.6K
Snippets: 27
Records: 51
Agent score: 78%

What's inside slim

Use custom TLDs for local domains
main
If you want to use a specific TLD instead of the default .test, provide the full domain name to the slim start command.
Note: Avoid using .local as it is reserved for mDNS and can cause slow DNS resolution on macOS/Linux.
```
slim start app.loc --port 3000   # https://app.loc → localhost:3000
slim start my.demo --port 4000   # https://my.demo → localhost:4000
```
```
slim start app.loc --port 3000
```
https://github.com/nilbuild/slim/blob/main/README.md
Install Slim
main
You can install Slim using a shell script or by building from source. Slim requires Go 1.25 or later and is supported on macOS and Linux.
Using the install script:
```
curl -sL https://slim.sh/install.sh | sh
```
Building from source:
```
git clone https://github.com/kamranahmedse/slim.git
cd slim
make build
make install
```
https://github.com/nilbuild/slim/blob/main/README.md

Manage local services with slim start and slim stop

main

Use slim start to map a domain to a local port and slim stop to remove the mapping.

Start a service:

slim start myapp --port 3000
slim start api --port 8080

Stop a service:

slim stop myapp                  # stop one domain
slim stop                        # stop all domains

slim start myapp --port 3000
slim start api --port 8080
slim stop myapp
slim stop

Share a local project via a public URL
main
You can expose your local server to the internet using a public slim.show URL. This requires you to run slim login first.
```
slim share --port 3000
# Result: https://cheeky-panda.slim.show
```
```
slim share --port 3000
```
https://github.com/nilbuild/slim/blob/main/README.md
Update and Uninstall Slim
main
To keep Slim up to date, use the update command. To completely remove Slim and all its associated configurations (CA, certs, hosts entries, port-forward rules, and config), use the uninstall command.
Update:
```
slim update
```
Uninstall:
```
slim uninstall
```
https://github.com/nilbuild/slim/blob/main/README.md
Quick Start with Slim
main
To create a custom HTTPS domain for local development, use the slim start command. By default, if you don't specify a TLD, Slim uses the .test TLD.
```
slim start myapp --port 3000
# Result: https://myapp.test → localhost:3000
```
```
slim start myapp --port 3000
```
https://github.com/nilbuild/slim/blob/main/README.md

Use the Slim CLI

main

Slim is a CLI tool used to map custom local domains to development server ports with HTTPS and WebSocket passthrough for HMR (Hot Module Replacement). It allows you to access your local services via friendly domains like myapp.test instead of localhost:3000.

slim start myapp --port 3000       # myapp.test → localhost:3000
slim start app.loc --port 3000     # app.loc → localhost:3000
slim start api --port 8080         # add another domain
slim list                          # see what's running
slim stop myapp                    # stop one domain
slim stop                          # stop everything

Configure multiple services using a .slim.yaml file
main
Define all services for a project in a .slim.yaml file at the project root. This allows you to manage complex setups with a single command.
Configuration Schema:
- services: A list of service objects.
  domain: The domain name (e.g., myapp).
  port: The local upstream port.
  routes: (Optional) A list of path-to-port mappings.
  path: The URL path.
  port: The upstream port for that path.
- log_mode: Logging verbosity (full | minimal | off).
- cors: Boolean to enable CORS headers on proxied responses.
Example .slim.yaml:
```
services:
  - domain: myapp
    port: 3000
    routes:
      - path: /api
        port: 8080
  - domain: dashboard
    port: 5173
  - domain: app.loc
    port: 4000
log_mode: minimal
cors: true
```
Commands for YAML configuration:
```
slim up                              # start all services defined in .slim.yaml
slim up --config /path/to/.slim.yaml # specify a custom config path
slim down                            # stop all project services
```
https://github.com/nilbuild/slim/blob/main/README.md
How the tunnel client handles reconnections
main
The tunnel.Client implements an automatic reconnection strategy. If the WebSocket connection is lost, the client enters a readLoop that attempts to reconnect using an exponential backoff strategy:
1. It starts with a 1-second backoff.
2. On failure, the backoff doubles (e.g., 2s, 4s, 8s...) up to a maximum of 30 seconds.
3. If the error is a registration failure (e.g., invalid credentials), the client stops attempting to reconnect and returns an error.
4. If the tunnel expires due to TTL (Status 4000) or is explicitly dropped (Status 4001), the client stops reconnecting.
https://github.com/nilbuild/slim/blob/main/internal/tunnel/client.go
Route URL paths to different upstream ports
main
You can route different URL paths on a single domain to different local ports using the --route flag.
```
slim start myapp --port 3000 --route /api=8080 --route /ws=9000
```
https://github.com/nilbuild/slim/blob/main/README.md

Configure ClientOptions for tunnel.Client

main

The ClientOptions struct defines how the tunnel client connects to the server and how it handles local traffic.

Field	Type	Description
`ServerURL`	`string`	The WebSocket URL of the Slim tunnel server.
`Token`	`string`	Authentication token for the tunnel.
`Subdomain`	`string`	Requested subdomain for the public URL.
`Domain`	`string`	Specific domain to use for the tunnel.
`LocalPort`	`int`	The port on `localhost` where your service is running.
`Password`	`string`	Password for tunnel authentication.
`TTL`	`time.Duration`	Time-to-live for the tunnel session.
`OnRequest`	`func(RequestEvent)`	Callback function triggered for every forwarded request.

type ClientOptions struct {
	ServerURL string
	Token     string
	Subdomain string
	Domain    string
	LocalPort int
	Password  string
	TTL       time.Duration
	OnRequest func(RequestEvent)
}

Inspect and debug Slim with list, logs, and doctor

main

Slim provides several commands for monitoring and troubleshooting your setup.

List running domains:

slim list                # inspect running domains
slim list --json       # output list in JSON format

View access logs:

slim logs                # view access logs
slim logs --follow myapp # tail logs for a specific domain
slim logs --flush        # clear the log file

Run diagnostics:

slim doctor              # run diagnostic checks for CA, trust, ports, hosts, daemon, and certs

slim list
slim logs --follow myapp
slim doctor