Quick start

This guide will get you from zero to a working GTProxy setup in just a few minutes. You’ll learn how to start the proxy, configure your Growtopia client to connect through it, and verify that packet interception is working.

Prerequisites

Before starting, make sure you have:

GTProxy installed (see Installation)
Growtopia client version 3.92 or newer
Basic familiarity with command line/terminal

Start the proxy

Launch GTProxy

Open a terminal and navigate to where you installed GTProxy, then run the executable:Windows:

GTProxy.exe

Linux/macOS:

./GTProxy

On first run, you’ll see output like this:

[2026-03-02 10:30:45.123] [12345] [info] Starting GTProxy (v3.0.0)
[2026-03-02 10:30:45.234] [12345] [warn] Configuration file "config.json" not found. Creating default configuration file...
[2026-03-02 10:30:45.345] [12345] [info] Default configuration file "config.json" created successfully.
[2026-03-02 10:30:45.456] [12345] [info] Config file "config.json" is all loaded up and ready to go!
[2026-03-02 10:30:45.567] [12345] [info] Loading scripts from: scripts/
[2026-03-02 10:30:45.678] [12345] [info] Loaded script: rainbow.lua
[2026-03-02 10:30:45.789] [12345] [info] HTTP server started on port 8080
[2026-03-02 10:30:45.890] [12345] [info] Proxy server listening on port 16999

Verify the proxy is running

GTProxy is ready when you see the message:

[info] Proxy server listening on port 16999

By default, GTProxy listens on:

Proxy server: Port 16999 (for game client connections)
HTTP server: Port 8080 (for metadata API)

These ports can be customized in config.json if needed.

Connect Growtopia to the proxy

Now that GTProxy is running, configure your Growtopia client to connect through it.

Launch Growtopia

Start your Growtopia client normally.

Connect to localhost

In Growtopia, instead of clicking “Connect,” you need to connect to the proxy server:

Open the server connection dialog
Enter server address: 127.0.0.1 or localhost
Enter port: 16999 (default GTProxy port)
Click connect

The exact method to specify a custom server varies by Growtopia client version. Some versions may require command-line arguments or configuration file edits.

Watch the proxy logs

When Growtopia connects, you’ll see activity in the GTProxy terminal:

[2026-03-02 10:32:15.123] [12345] [info] Client connected from 127.0.0.1:54321
[2026-03-02 10:32:15.234] [12345] [info] Connecting to Growtopia server: www.growtopia1.com:17091
[2026-03-02 10:32:15.456] [12345] [info] Connected to game server
[2026-03-02 10:32:15.567] [12345] [info] Forwarding packets between client and server

This confirms that GTProxy is successfully intercepting traffic between your client and the Growtopia servers.

Verify packet interception

Let’s confirm that GTProxy is capturing and logging packets.

Check packet logs

With default logging settings, GTProxy will print packet information to the console. Look for output like:

[2026-03-02 10:32:16.123] [12345] [debug] [Client → Server] Variant packet: OnSuperMainStartAcceptLogonHrdxs47254722215a
[2026-03-02 10:32:16.234] [12345] [debug] [Server → Client] Game update packet: LOAD_MAP
[2026-03-02 10:32:16.345] [12345] [info] [Server → Client] Variant: OnConsoleMessage|Welcome to Growtopia!

Adjust logging verbosity

Control what gets logged by editing config.json:

{
  "server": {
    "port": 16999,
    "address": "www.growtopia1.com"
  },
  "client": {
    "game_version": "5.39",
    "protocol": 225,
    "dns_server": "cloudflare"
  },
  "log": {
    "print_message": true,
    "print_game_update_packet": false,
    "print_variant": true,
    "print_extra": true
  },
  "command": {
    "prefix": "/"
  }
}

Toggle these flags to control logging:

print_message - Log text messages and chat
print_game_update_packet - Log game update packets (position, state changes)
print_variant - Log variant function calls (most game actions)
print_extra - Log additional packet metadata

Restart GTProxy

After modifying config.json, stop GTProxy (Ctrl+C) and restart it to apply changes:

# GTProxy automatically reloads config.json on startup
./GTProxy

Try built-in commands

GTProxy includes several built-in commands you can use from within the game.

List available commands

In Growtopia chat, type:

/help

You’ll see a list of available proxy commands in the game console.

Test a command

Try the debug command to toggle additional information:

/debug

Or change your display name:

/nick CustomName

Commands use the / prefix by default. This can be changed in config.json under command.prefix.

Explore Lua scripting

GTProxy includes a powerful Lua scripting engine for extending functionality without recompiling.

Check loaded scripts

On startup, GTProxy automatically loads all .lua files from the scripts/ directory. Check the startup logs:

[info] Loading scripts from: scripts/
[info] Loaded script: rainbow.lua
[info] Loaded script: test_event.lua
[info] Loaded script: test_scheduler.lua

Create your first script

Create a new file scripts/hello.lua:

-- Log a message when the script loads
logger.info("Hello from Lua script!")

-- Register a custom command
command.register("hello", "Say hello", function(ctx)
    logger.info("Hello, world!")
    return true
end)

-- Listen for packets
event.on("server:SendToServer", function(ctx)
    if ctx:has_packet() then
        local pkt = ctx:parse()
        logger.debug("Intercepted packet from client")
    end
end)

Reload GTProxy

Restart GTProxy to load your new script:

# Stop with Ctrl+C, then restart
./GTProxy

You should see:

[info] Loaded script: hello.lua
[info] Hello from Lua script!

Now you can use /hello in-game to trigger your custom command.

Access the HTTP API

GTProxy includes a built-in HTTP server that exposes game metadata.

Check the HTTP server status

The HTTP server starts automatically and listens on port 8080:

[info] HTTP server started on port 8080

Query the API

You can access metadata endpoints from your browser or tools like curl:

# Example: Query game state
curl http://localhost:8080/api/state

# Example: Get player information
curl http://localhost:8080/api/player

The API provides access to world data, player state, item database, and other game information extracted by the proxy.

Common configuration

Here are some common configuration tweaks you might want to make in config.json:

Change proxy port

{
  "server": {
    "port": 17091,  // Changed from default 16999
    "address": "www.growtopia1.com"
  }
}

Update game version

If Growtopia releases an update:

{
  "client": {
    "game_version": "5.40",  // Update to match client
    "protocol": 226,          // Update if protocol changes
    "dns_server": "cloudflare"
  }
}

Disable verbose logging

For production use, reduce log spam:

{
  "log": {
    "print_message": false,
    "print_game_update_packet": false,
    "print_variant": false,
    "print_extra": false
  }
}

Change command prefix

Use a different command prefix:

{
  "command": {
    "prefix": "!"  // Commands now use ! instead of /
  }
}

Next steps

Now that you have GTProxy running, explore these topics:

Configuration reference

Learn about all available configuration options

Lua scripting guide

Write custom scripts to extend GTProxy functionality

Packet reference

Understand Growtopia packet structure and types

Command reference

Complete list of built-in proxy commands

Troubleshooting

Growtopia won’t connect to proxy

Verify GTProxy is running and shows “Proxy server listening on port 16999”
Check that you’re connecting to 127.0.0.1:16999 in Growtopia
Ensure no firewall is blocking port 16999
Try running GTProxy as administrator (Windows) or with sudo (Linux/macOS)

Proxy connects but can’t reach Growtopia servers

Check your internet connection
Verify the server address in config.json is correct (www.growtopia1.com)
Try a different DNS server in config: "dns_server": "google" or "dns_server": "cloudflare"

No packets showing in logs

Verify logging is enabled in config.json (see log configuration above)
Check that GTProxy shows “Forwarding packets between client and server”
Increase log verbosity by setting all log flags to true

Scripts not loading

Ensure .lua files are in the scripts/ directory relative to where GTProxy runs
Check the startup logs for syntax errors in your Lua scripts
Verify file permissions allow GTProxy to read the scripts

Get Started

Core Concepts

Commands

Lua Scripting

Configuration

Advanced

Quick start

Quick start

Prerequisites

Start the proxy

Connect Growtopia to the proxy

Verify packet interception

Try built-in commands

Explore Lua scripting

Access the HTTP API

Common configuration

Change proxy port

Update game version

Disable verbose logging

Change command prefix

Next steps

Configuration reference

Lua scripting guide

Packet reference

Command reference

Troubleshooting

Growtopia won’t connect to proxy

Proxy connects but can’t reach Growtopia servers

No packets showing in logs

Scripts not loading

Build docs developers (and LLMs) love

Get Started

Core Concepts

Commands

Lua Scripting

Configuration

Advanced

Documentation Index

​Quick start

​Prerequisites

​Start the proxy

​Connect Growtopia to the proxy

​Verify packet interception

​Try built-in commands

​Explore Lua scripting

​Access the HTTP API

​Common configuration

​Change proxy port

​Update game version

​Disable verbose logging

​Change command prefix

​Next steps

Configuration reference

Lua scripting guide

Packet reference

Command reference

​Troubleshooting

​Growtopia won’t connect to proxy

​Proxy connects but can’t reach Growtopia servers

​No packets showing in logs

​Scripts not loading

Build docs developers (and LLMs) love

Quick start

Prerequisites

Start the proxy

Connect Growtopia to the proxy

Verify packet interception

Try built-in commands

Explore Lua scripting

Access the HTTP API

Common configuration

Change proxy port

Update game version

Disable verbose logging

Change command prefix

Next steps

Troubleshooting

Growtopia won’t connect to proxy

Proxy connects but can’t reach Growtopia servers

No packets showing in logs

Scripts not loading