This is not an official KGS page.

kgsGtp documentation

This page is out of date. Instead, please read the documentation that was included with your download of kgsGtp.


GTP (Go Text Protocol) is a protocol that allows computer go playing programs (called "engines") to communicate with other programs. It was designed to be an improvement on the older "Go Modem Protocol". It is easy to implement and very useful for controlling go programs. Documentation on this standard can be found at the GTP home page.

There is a KGS client called kgsGtp which understands both GTP and the KGS server's protocol. It can serve as a bridge, connecting the GTP engine to the KGS server, allowing the GTP engine to play on KGS.

How to Run kgsGtp

First, you need to create an account on KGS, using the standard KGS client. Then you need to set up a configuration file for kgsGtp. Lastly, you need to run both it and the GTP engine together. Since kgsGtp is a java program that comes bundled as a jar file, you usually run it with a command line like this:

java -jar kgsGtp.jar <config file> <extra options>

kgsGtp requires java 1.5 or later to run. No external libraries are needed.

When you run kgsGtp, you must specify a config file. This is a standard Java properties file. It is plain text, with one option specified per line, in the format:


Like all java properties files, the file is encoded in ISO-8859-1; if you need to represent other characters, you will need to use escape sequences. The standard Java programs "native2ascii" or "ascii2native" is the best way to write these secape sequences. Search for more information on using these tools.

In addition to these options, you can put options in the command line. Any options in both the command line and the config file will use the command line value and ignore what is in the config file.

Connecting kgsGtp to the GTP Engine

There are five ways that kgsGtp can be connected to the GTP engine:

1. Have kgsGtp start the engine

To do this, just use the "engine=engine command line" option in either the config file or on the command line. The engine must read from its standard input to get the GTP commands, and write its responses to its standard output.

2. Use named pipes

You need two named pipes - one for the engine to kgsGtp, and one for kgsGtp to the engine. Run kgsGtp, and instead of specifying the engine, you need to specify " to kgsGtp file" and "gtp.out=kgsGtp to engine file". If you have an engine set, that will override these settings, and they will be ignored!

3. Use TCP/IP sockets

If you specify "engine.port=port number" then kgsGtp will open up a TCP port and start listening. It expects the next inbound connection to be the engine.

4. Use stdin/stdout

This system is used if no options are present. You just need to make sure that stdin for kgsGtp it connected to the engine's output and stdout for kgsGtp is connected to the engine's input. Usually, the easiest way to do this is by forking and execing kgsGtp from within your engine.

5. Use kgsGtp as a library in a Java engine

kgsGtp can be used as a library in a java engine. You need to construct a set of configuration options, construct the client, then tell it to start:

package org.igoweb.igoweb.client.gtp;

public class GtpClient {

   * Create a new GTP Client.
   * @param in An input stream that will give us any responses from the engine.
   * @param out An output stream that will go to the engine with our commands.
   * @param args Our options.
  public GtpClient( in, out,
                   Options options);

   * Connect to the server and operate the GTP interface.
   * @return <code>true</code> on success, <code>false</code> if we were
   *   unable to do what was requested.
  public boolean go();

public class Options {

   * Construct a new set of options for the kgsGtp client by pulling values
   * out of a set of properties. Any values that we use will be removed from
   * the properties, so anything left over is unused.
   * @param props The properties that holds our options as string values.
   * @param logName The name of the java logger that we will construct.
   * @throws IllegalArgumentException If any required values are missing or if
   *   any illegal values are detected.
  public Options(java.util.Properties props, String logName);

Just add kgsGtp.jar to your classpath, then construct a set of options from a Properties object. Once you have the options, you can construct a client. The input and output streams must be from your engine. Once you have build a GTP client, just call go() and it will start running. It will return only after shutting down.

kgsGtp Options

Running kgsGtp with the single option -help lists all options. Here is a more detailed list:

Logging Options
logFile Specifies that logging should be done to a file instead of to stderr. The value is the name of the file to use.
verbose Setting this to t will make kgsGtp emit a lot of logging info. Every message between kgsGtp and the engine will be logged and a lot of KGS server events will be logged as well.
Engine Connection Options Specifies a named pipe to read GTP responses from. Ignored if the option engine is set.
gtp.out Specifies a named pipe to write GTP commands to. Ignored if the option engine is set.
engine Specifies the command line to run to create the engine.
KGS Connection Options Sets the host name or IP address of the KGS server. You only need to set this if you are tunneling through a port forwarder (for example, to get through a firewall).
server.port Sets the TCP port of the KGS server. You only need to set this if you are going through a port forwarder.
reconnect If set, the client will try to reconnect to the server if it gets cut off. It will not reconnect if the GTP engine dies or if there is an error in the GTP protocol.
name The user name of your KGS account. Required.
password The password of your KGS account. Required.
room The room that the engine should join. If this isn't set, then it will join the same room it was in last time it connected. The engine can only be in one room.
open Setting this to t will make the engine create an open game and wait for challenges. Either this, tournament, or opponent must be specified.
opponent Sets the user name who the engine is to play. If open is set, then any challenges that come from any other user will be declined. If open is not set, then the engine will look for open games by the given opponent, and challenge them. Either this, open, or tournament must be specified.
tournament Setting this to t indicates that you intend to be playing in a tournament. All tournament games will be accepted, all others will be ignored. Either this, open, or opponent must be specified.
undo Setting this to f will refuse all undos. Normally, undo is allowed in free games the engine allows it and refused in ranked games.
Options on the servers
talk If anybody tries to talk to the engine in a private conversation, it will answer with this message. Should be something like "I'm a computer program and cannot talk."
hint.noArguing If your engine does not support the kgs-genmove_cleanup command (or the game uses Japanese rules, where kgs-genmove_cleanup can't be used), and your opponent does not agree with the dead stones that the engine settled on, then this message will be written to your opponent. It should tell them that they must either agree with the engine or leave the game. The default message does exactly that, in English.
hint.cleanup If kgs-genmove_cleanup is usable in this game, and your opponent disagrees on which stones are dead, then this message is sent to them. It should tell them to undo if they want to play out the game to determine which stones are dead. The default message says exactly that, in English.
gameNotes Sets the notes that will appear in any open games that are created.
rules Should be one of japanese, chinese, aga, or newzealand. Sets the rules that will be used when it creates an open game. People can override this though, so this doesn't guarantee that the rules will actually be used.
rules.boardSize Sets the size of the board that will be in open games. Again, it can be overridden.
rules.time Sets the time system that will appear in open games. There are several formats:
  • "0" for no time limit.
  • "m:ss" for absolute time. For example, 30:00 for a game where each player has a half hour for all their moves.
  • "m:ss+nxm:ss" for byo-yomi time. For example, 30:00+5x0:30 for a half hour of main time and 5 byo-yomi periods of 30 seconds each.
  • "m:ss+n/m:ss" for canadian time. For example, 30:00+25/10:00 means a half hour of main time, with 10 minute byo-yomi periods of 25 stones each.

Example kgsGtp Config File

This example config file was used when I was testing kgsGtp. It connects as "gtpProg" and plays anybody who challenges. Gnugo is run by kgsGtp to provide the engine.

room=English Room
gameNotes=Connecting GnuGo to KGS
engine=/home/wms/src/gnugo-3.4/interface/gnugo --mode gtp

kgsGtp's use of GTP

kgsGtp does not use all of GTP's commands. Only a very small set of commands (three, in fact) are absolutely required. Any non-required commands may be sent to the engine, but it is acceptable for the engine to simply return errors for all of them. These are the commands that it will send to engines:

Administrative Commands

Sent when first connecting to the client. kgsGtp will never send nonstandard commands unless the engine states that they are supported. kgsGtp may send standard commands even though the engine does not claim to support them. If you do not support list_commands then only very basic functionality will be used in your engine.
The name and version are added as comments every time that kgsGtp starts a game. If the engine does not provide a name and version, then nothing will be written. If you use non-ASCII characters in the name or version of your engine, these characters must be encoded using UTF-8.
If clear_board is not supported, then we send a quit after the game ends because there is nothing else we can do. If the quit fails, then we just close everything up with an error.

Setup Commands

This will be sent before the game starts. If you cannot play the size specified, reply with an error. Any challenges that come with board sizes that your engine cannot support will not be accepted. Note that you will often get multiple boardsize commands before the game start - one or more as each challenge comes in to ensure that your engine can play the board size specified, then a final boardsize when the game actually starts.
Used before each game to ensure a clean starting point. If you don't support this, then you will be limited to one game for each time you run kgsGtp.
Sent when each game starts up.
Used to set or ask for handicap stone positions. The fixed handicap GTP command is not used. If the game is fixed handicap, you will get the set_free_handicap command instead. GTP does not have enough flexibility in its fixed handicap command to support KGS. If your engine does not support these commands then handicap games will be refused.

Core Play Commands

Used as normal.
If your engine supports this command, you will get it as normal. If your engine does not include undo as a response to list_commands, then KGS will use clear_board followed by a series of play commands when an undo is required. If your engine supports neither of these commands, then any undos that your opponents request will be denied.

Tournament Commands

Similar to the boardsize command, you may get several time settings commands; any settings that your engine cannot play with, you should return an error. If your engine supports the kgs-time_settings command, then you will get that instead of the standard time_settings command. The reson for the KGS-specific time setting is that GTP's standard time settings has no way to describe the byo-yomi time system. This system is quite popular in tournaments and is used often on KGS. The format for the kgs-time_settings command is the same as time_settings, but another parameter is inserted as the first parameter, which describes the time system as either none, absolute, byoyomi, or canadian. For the none and absolute time systems there will be fewer than two options. If you do not support kgs-time_settings and your engine is put into a byo-yomi game, kgsGtp will tell your engine that it is an absolute time game with no byo-yomi periods and a total time equal to the main time and all of the periods.
Used as normal.
final_status_listOptional, required for rated games
After the game enters scoring kgsGtp will send this command, asking for dead stones. kgsGtp will never ask questions about seki, only about dead stones. If you successfully return a list of dead stones, then kgsGtp will mark those on the board. If you return an error, then kgsGtp will not mark any stones dead and your opponent will have to do that instead.
kgs-genmove_cleanupOptional, recommended for playing ranked games
This is a kgsGtp-specific command. Engines that support it should treat it the same as the genmove command, except that they should not pass until all dead stones are removed from the board. This is used by kgsGtp when the engine and the opponent disagree on which stones are dead at the end of the game.

KGS and Ranked Games

It is important that ranked games do not allow people to "cheat" and abuse the engine or kgsGtp to inflate their personal ranks. The possible ways to cheat include:

  1. Marking living stones dead, or dead stones living, to change the score of a lost game to a won game.
  2. Escaping from games that you are losing.
  3. Setting time parameters so that the engine cannot hope to win (for example, if the engine always uses at least 5 seconds per move, you can set the time to give only 3 seconds per move, then play random moves very fast until you win).
  4. Running kgsGtp in your own account to inflate your rank (this obviously only works if you have an engine that is stronger than yourself).
  5. Running the engine standalone, and copying its moves into your games that you play with the standard client.

Clearly there is no way to stop #5, but fortunately that technique is fairly tedious so most players probably will not be interested in doing that.

To try to keep a handle on ranked game play on the server, to prevent players from cheating on the engines (or using engines to cheat for themselves), kgsGtp will behave as follows when playing ranked games:

  1. "Normal" accounts cannot play ranked games when connected by GTP, only when using one of the "human" clients.
  2. Accounts can be set to "Ranked Robot" authorization. Please email to to ask for this authorization. Once it is set for an account, the GTP engine can play ranked against other GTP engines or against "human" clients, and humans who log in to that account cannot play ranked games.
  3. A kgsGtp engine will refuse to start a new ranked game with a player if there is already an unfinished ranked game against that player.
  4. To play ranked games, an engine must support the final_status_list command.
  5. All undos are declined in ranked games.
  6. The kgsGtp engine will refuse to play ranked unless the rules of the game exactly match what is specified in the configuration file and/or command line.
  7. If the engine and the human disagree on the status of living and dead stones at the end of the game, one of two things will happen: If the game uses non-Japanese rules and the engine supports the kgs-genmove_cleanup command, then kgsGtp will recommend that the human press "undo", after which play will continue but the engine will get kgs-genmove_cleanup commands (in place of genmove commands). In all other cases, kgsGtp will simply refuse to finish the game unless the human agrees to the dead stones that the engine listed in its response to the final_status_list command.
  8. It is recommended that engines that play ranked games support the kgs-genmove_cleanup command and play non-Japanese rules games. It is especially important that your engine support that command if it isn't so good at computing living/dead groups at the end of the game, otherwise you will get a lot of angry opponents left standing around in an unfinished game!


Version 2.6.11:

Version 2.6.10:

Version 2.6.2:

Version 2.5.9:

Version 2.5.8 beta2:

Version 2.5.8:

Version 2.5.7:

Version 2.5.6:

Version 2.5.6 beta6:

Version 2.5.6 beta5:

Version 2.5.6 beta4:

Version 2.5.6 beta3:

Version 2.5.6 beta2: